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/01/13 04:46:20 UTC
svn commit: r1724348 [4/6] - in
/incubator/singa/site/trunk/content/markdown/docs: ./ jp/ kr/
Added: incubator/singa/site/trunk/content/markdown/docs/kr/communication.md
URL: http://svn.apache.org/viewvc/incubator/singa/site/trunk/content/markdown/docs/kr/communication.md?rev=1724348&view=auto
==============================================================================
--- incubator/singa/site/trunk/content/markdown/docs/kr/communication.md (added)
+++ incubator/singa/site/trunk/content/markdown/docs/kr/communication.md Wed Jan 13 03:46:19 2016
@@ -0,0 +1,453 @@
+# Communication
+
+---
+
+Different messaging libraries has different benefits and drawbacks. For instance,
+MPI provides fast message passing between GPUs (using GPUDirect), but does not
+support fault-tolerance well. On the contrary, systems using ZeroMQ can be
+fault-tolerant, but does not support GPUDirect. The AllReduce function
+of MPI is also missing in ZeroMQ which is efficient for data aggregation for
+distributed training. In Singa, we provide general messaging APIs for
+communication between threads within a process and across processes, and let
+users choose the underlying implementation (MPI or ZeroMQ) that meets their requirements.
+
+Singa's messaging library consists of two components, namely the message, and
+the socket to send and receive messages. **Socket** refers to a
+Singa defined data structure instead of the Linux Socket.
+We will introduce the two components in detail with the following figure as an
+example architecture.
+
+<img src="../images/arch/arch2.png" style="width: 550px"/>
+<img src="../images/arch/comm.png" style="width: 550px"/>
+<p><strong> Fig.1 - Example physical architecture and network connection</strong></p>
+
+Fig.1 shows an example physical architecture and its network connection.
+[Section-partition server side ParamShard](architecture.html}) has a detailed description of the
+architecture. Each process consists of one main thread running the stub and multiple
+background threads running the worker and server tasks. The stub of the main
+thread forwards messages among threads . The worker and
+server tasks are performed by the background threads.
+
+## Message
+
+<object type="image/svg+xml" style="width: 100px" data="../images/msg.svg" > Not
+supported </object>
+<p><strong> Fig.2 - Logical message format</strong></p>
+
+Fig.2 shows the logical message format which has two parts, the header and the
+content. The message header includes the sender's and receiver's IDs, each consisting of
+the group ID and the worker/server ID within the group. The stub forwards
+messages by looking up an address table based on the receiver's ID.
+There are two sets of messages according to the message type defined below.
+
+ * kGet/kPut/kRequest/kSync for messages about parameters
+
+ * kFeaBlob/kGradBlob for messages about transferring feature and gradient
+ blobs of one layer to its neighboring layer
+
+There is a target ID in the header. If the message body is parameters,
+the target ID is then the parameter ID. Otherwise the message is related to
+layer feature or gradient, and the target ID consists of the layer ID and the
+blob ID of that layer. The message content has multiple frames to store the
+parameter or feature data.
+
+The API for the base Msg is:
+
+ /**
+ * Msg used to transfer Param info (gradient or value), feature blob, etc
+ * between workers, stubs and servers.
+ *
+ * Each msg has a source addr and dest addr identified by a unique integer.
+ * It is also associated with a target field (value and version) for ease of
+ * getting some meta info (e.g., parameter id) from the msg.
+ *
+ * Other data is added into the message as frames.
+ */
+ class Msg {
+ public:
+ ~Msg();
+ Msg();
+ /**
+ * Construct the msg providing source and destination addr.
+ */
+ Msg(int src, int dst);
+ /**
+ * Copy constructor.
+ */
+ Msg(const Msg& msg);
+ /**
+ * Swap the src/dst addr
+ */
+ void SwapAddr();
+ /**
+ * Add a frame (a chunk of bytes) into the message
+ */
+ void AddFrame(const void* addr, int nBytes);
+ /**
+ * @return num of bytes of the current frame.
+ */
+ int FrameSize();
+ /**
+ * @return the pointer to the current frame data.
+ */
+ void* FrameData();
+ /**
+ * @return the data of the current frame as c string
+ */
+ char* FrameStr();
+ /**
+ * Move the cursor to the first frame.
+ */
+ void FirstFrame();
+ /**
+ * Move the cursor to the last frame.
+ */
+ void LastFrame();
+ /**
+ * Move the cursor to the next frame
+ * @return true if the next frame is not NULL; otherwise false
+ */
+ bool NextFrame();
+ /**
+ * Add a 'format' frame to the msg (like CZMQ's zsock_send).
+ *
+ * The format is a string that defines the type of each field.
+ * The format can contain any of these characters, each corresponding to
+ * one or two arguments:
+ * i = int (signed)
+ * 1 = uint8_t
+ * 2 = uint16_t
+ * 4 = uint32_t
+ * 8 = uint64_t
+ * p = void * (sends the pointer value, only meaningful over inproc)
+ * s = char**
+ *
+ * Returns size of the added content.
+ */
+ int AddFormatFrame(const char *format, ...);
+ /**
+ * Parse the current frame added using AddFormatFrame(const char*, ...).
+ *
+ * The format is a string that defines the type of each field.
+ * The format can contain any of these characters, each corresponding to
+ * one or two arguments:
+ * i = int (signed)
+ * 1 = uint8_t
+ * 2 = uint16_t
+ * 4 = uint32_t
+ * 8 = uint64_t
+ * p = void * (sends the pointer value, only meaningful over inproc)
+ * s = char**
+ *
+ * Returns size of the parsed content.
+ */
+ int ParseFormatFrame(const char* format, ...);
+
+ #ifdef USE_ZMQ
+ void ParseFromZmsg(zmsg_t* msg);
+ zmsg_t* DumpToZmsg();
+ #endif
+
+ /**
+ * @return msg size in terms of bytes, ignore meta info.
+ */
+ int size() const;
+ /**
+ * Set source addr.
+ * @param addr unique identify one worker/server/stub in the current job
+ */
+ void set_src(int addr) { src_ = addr; }
+ /**
+ * @return source addr.
+ */
+ int src() const { return src_; }
+ /**
+ * Set destination addr.
+ * @param addr unique identify one worker/server/stub in the current job
+ */
+ void set_dst(int addr) { dst_ = addr; }
+ /**
+ * @return dst addr.
+ */
+ int dst() const { return dst_; }
+ /**
+ * Set msg type, e.g., kPut, kGet, kUpdate, kRequest
+ */
+ void set_type(int type) { type_ = type; }
+ /**
+ * @return msg type.
+ */
+ int type() const { return type_; }
+ /**
+ * Set msg target.
+ *
+ * One msg has a target to identify some entity in worker/server/stub.
+ * The target is associated with a version, e.g., Param version.
+ */
+ void set_trgt(int val, int version) {
+ trgt_val_ = val;
+ trgt_version_ = version;
+ }
+ int trgt_val() const {
+ return trgt_val_;
+ }
+ int trgt_version() const {
+ return trgt_version_;
+ }
+
+ };
+
+In order for a Msg object to be routed, the source and dest address should be attached.
+This is achieved by calling the set_src and set_dst methods of the Msg object.
+The address parameter passed to these two methods can be manipulated via a set of
+helper functions, shown as below.
+
+ /**
+ * Wrapper to generate message address
+ * @param grp worker/server group id
+ * @param id_or_proc worker/server id or procs id
+ * @param type msg type
+ */
+ inline int Addr(int grp, int id_or_proc, int type) {
+ return (grp << 16) | (id_or_proc << 8) | type;
+ }
+
+ /**
+ * Parse group id from addr.
+ *
+ * @return group id
+ */
+ inline int AddrGrp(int addr) {
+ return addr >> 16;
+ }
+ /**
+ * Parse worker/server id from addr.
+ *
+ * @return id
+ */
+ inline int AddrID(int addr) {
+ static const int mask = (1 << 8) - 1;
+ return (addr >> 8) & mask;
+ }
+
+ /**
+ * Parse worker/server procs from addr.
+ *
+ * @return procs id
+ */
+ inline int AddrProc(int addr) {
+ return AddrID(addr);
+ }
+ /**
+ * Parse msg type from addr
+ * @return msg type
+ */
+ inline int AddrType(int addr) {
+ static const int mask = (1 << 8) -1;
+ return addr & mask;
+ }
+
+
+## Socket
+
+In SINGA, there are two types of sockets, the Dealer Socket and the Router
+Socket, whose names are adapted from ZeroMQ. All connections are of the same type, i.e.,
+Dealer<-->Router. The communication between dealers and routers are
+asynchronous. In other words, one Dealer
+socket can talk with multiple Router sockets, and one Router socket can talk
+with multiple Dealer sockets.
+
+### Base Socket
+
+The basic functions of a Singa Socket is to send and receive messages. The APIs
+are:
+
+ class SocketInterface {
+ public:
+ virtual ~SocketInterface() {}
+ /**
+ * Send a message to connected socket(s), non-blocking. The message
+ * will be deallocated after sending, thus should not be used after
+ * calling Send();
+ *
+ * @param msg The message to be sent
+ * @return 1 for success queuing the message for sending, 0 for failure
+ */
+ virtual int Send(Msg** msg) = 0;
+ /**
+ * Receive a message from any connected socket.
+ *
+ * @return a message pointer if success; nullptr if failure
+ */
+ virtual Msg* Receive() = 0;
+ /**
+ * @return Identifier of the implementation dependent socket. E.g., zsock_t*
+ * for ZeroMQ implementation and rank for MPI implementation.
+ */
+ virtual void* InternalID() const = 0;
+ };
+
+A poller class is provided to enable asynchronous communication between routers and dealers.
+One can register a set of SocketInterface objects with a poller instance via calling its Add method, and
+then call the Wait method of this poll object to wait for the registered SocketInterface objects to be ready
+for sending and receiving messages. The APIs of the poller class is shown below.
+
+ class Poller {
+ public:
+ Poller();
+ Poller(SocketInterface* socket);
+ /**
+ * Add a socket for polling; Multiple sockets can be polled together by
+ * adding them into the same poller.
+ */
+ void Add(SocketInterface* socket);
+ /**
+ * Poll for all sockets added into this poller.
+ * @param timeout Stop after this number of mseconds
+ * @return pointer To the socket if it has one message in the receiving
+ * queue; nullptr if no message in any sockets,
+ */
+ SocketInterface* Wait(int duration);
+
+ /**
+ * @return true if the poller is terminated due to process interupt
+ */
+ virtual bool Terminated();
+ };
+
+
+### Dealer Socket
+
+The Dealer socket inherits from the base Socket. In Singa, every Dealer socket
+only connects to one Router socket as shown in Fig.1. The connection is set up
+by connecting the Dealer socket to the endpoint of a Router socket.
+
+ class Dealer : public SocketInterface {
+ public:
+ /*
+ * @param id Local dealer ID within a procs if the dealer is from worker or
+ * server thread, starts from 1 (0 is used by the router); or the connected
+ * remote procs ID for inter-process dealers from the stub thread.
+ */
+ Dealer();
+ explicit Dealer(int id);
+ ~Dealer() override;
+ /**
+ * Setup the connection with the router.
+ *
+ * @param endpoint Identifier of the router. For intra-process
+ * connection, the endpoint follows the format of ZeroMQ, i.e.,
+ * starting with "inproc://"; in Singa, since each process has one
+ * router, hence we can fix the endpoint to be "inproc://router" for
+ * intra-process. For inter-process, the endpoint follows ZeroMQ's
+ * format, i.e., IP:port, where IP is the connected process.
+ * @return 1 connection sets up successfully; 0 otherwise
+ */
+ int Connect(const std::string& endpoint);
+ int Send(Msg** msg) override;
+ Msg* Receive() override;
+ void* InternalID() const override;
+ };
+
+### Router Socket
+
+The Router socket inherits from the base Socket. One Router socket connects to
+at least one Dealer socket. Upon receiving a message, the router forwards it to
+the appropriate dealer according to the receiver's ID of this message.
+
+ class Router : public SocketInterface {
+ public:
+ Router();
+ /**
+ * There is only one router per procs, hence its local id is 0 and is not set
+ * explicitly.
+ *
+ * @param bufsize Buffer at most this number of messages
+ */
+ explicit Router(int bufsize);
+ ~Router() override;
+ /**
+ * Setup the connection with dealers.
+ *
+ * It automatically binds to the endpoint for intra-process communication,
+ * i.e., "inproc://router".
+ *
+ * @param endpoint The identifier for the Dealer socket in other process
+ * to connect. It has the format IP:Port, where IP is the host machine.
+ * If endpoint is empty, it means that all connections are
+ * intra-process connection.
+ * @return number of connected dealers.
+ */
+ int Bind(const std::string& endpoint);
+ /**
+ * If the destination socket has not connected yet, buffer this the message.
+ */
+ int Send(Msg** msg) override;
+ Msg* Receive() override;
+ void* InternalID() const override;
+
+ };
+
+## Implementation
+
+### ZeroMQ
+
+**Why [ZeroMQ](http://zeromq.org/)?** Our previous design used MPI for
+communication between Singa processes. But MPI is a poor choice when it comes
+to fault-tolerance, because failure at one node brings down the entire MPI
+cluster. ZeroMQ, on the other hand, is fault tolerant in the sense that one
+node failure does not affect the other nodes. ZeroMQ consists of several basic
+communication patterns that can be easily combined to create more complex
+network topologies.
+
+<img src="../images/msg-flow.png" style="width: 550px"/>
+<p><strong> Fig.3 - Messages flow for ZeroMQ</strong></p>
+
+The communication APIs of Singa are similar to the DEALER-ROUTER pattern of
+ZeroMQ. Hence we can easily implement the Dealer socket using ZeroMQ's DEALER
+socket, and Router socket using ZeroMQ's ROUTER socket.
+The intra-process can be implemented using ZeroMQ's inproc transport, and the
+inter-process can be implemented using the tcp transport (To exploit the
+Infiniband, we can use the sdp transport). Fig.3 shows the message flow using
+ZeroMQ as the underlying implementation. The messages sent from dealers has two
+frames for the message header, and one or more frames for the message content.
+The messages sent from routers have another frame for the identifier of the
+destination dealer.
+
+Besides the DEALER-ROUTER pattern, we may also implement the Dealer socket and
+Router socket using other ZeroMQ patterns. To be continued.
+
+### MPI
+
+Since MPI does not provide intra-process communication, we have to implement
+it inside the Router and Dealer socket. A simple solution is to allocate one
+message queue for each socket. Messages sent to one socket is inserted into the
+queue of that socket. We create a SafeQueue class to ensure the consistency of
+the queue. All queues are created by the main thread and
+passed to all sockets' constructor via *args*.
+
+ /**
+ * A thread safe queue class.
+ * There would be multiple threads pushing messages into
+ * the queue and only one thread reading and popping the queue.
+ */
+ class SafeQueue{
+ public:
+ void Push(Msg* msg);
+ Msg* Front();
+ void Pop();
+ bool empty();
+ };
+
+For inter-process communication, we serialize the message and call MPI's
+send/receive functions to transfer them. All inter-process connections are
+setup by MPI at the beginning. Consequently, the Connect and Bind functions do
+nothing for both inter-process and intra-process communication.
+
+MPI's AllReduce function is efficient for data aggregation in distributed
+training. For example, [DeepImage of Baidu](http://arxiv.org/abs/1501.02876)
+uses AllReduce to aggregate the updates of parameter from all workers. It has
+similar architecture as [Fig.2](architecture.html),
+where every process has a server group and is connected with all other processes.
+Hence, we can implement DeepImage in Singa by simply using MPI's AllReduce function for
+inter-process communication.
Added: incubator/singa/site/trunk/content/markdown/docs/kr/data.md
URL: http://svn.apache.org/viewvc/incubator/singa/site/trunk/content/markdown/docs/kr/data.md?rev=1724348&view=auto
==============================================================================
--- incubator/singa/site/trunk/content/markdown/docs/kr/data.md (added)
+++ incubator/singa/site/trunk/content/markdown/docs/kr/data.md Wed Jan 13 03:46:19 2016
@@ -0,0 +1,98 @@
+# Data Preparation
+
+---
+
+SINGA uses input layers to load data.
+Users can store their data in any format (e.g., CSV or binary) and at any places
+(e.g., disk file or HDFS) as long as there are corresponding input layers that
+can read the data records and parse them.
+
+To make it easy for users, SINGA provides a [StoreInputLayer] to read data
+in the format of (string:key, string:value) tuples from a couple of sources.
+These sources are abstracted using a [Store]() class which is a simple version of
+the DB abstraction in Caffe. The base Store class provides the following operations
+for reading and writing tuples,
+
+ Open(string path, Mode mode); // open the store for kRead or kCreate or kAppend
+ Close();
+
+ Read(string* key, string* val); // read a tuple; return false if fail
+ Write(string key, string val); // write a tuple
+ Flush();
+
+Currently, two implementations are provided, namely
+
+1. [KVFileStore] for storing tuples in [KVFile]() (a binary file).
+The *create_data.cc* files in *examples/cifar10* and *examples/mnist* provide
+examples of storing records using KVFileStore.
+
+2. [TextFileStore] for storing tuples in plain text file (one line per tuple).
+
+The (key, value) tuple are parsed by subclasses of StoreInputLayer depending on the
+format of the tuple,
+
+* [ProtoRecordInputLayer] parses the value field from one
+tuple into a [SingleLabelImageRecord], which is generated by Google Protobuf according
+to [common.proto]. It can be used to store features for images (e.g., using the pixel field)
+or other objects (using the data field). The key field is not used.
+
+* [CSVRecordInputLayer] parses one tuple as a CSV line (separated by comma).
+
+
+## Using built-in record format
+
+SingleLabelImageRecord is a built-in record in SINGA for storing image features.
+It is used in the cifar10 and mnist examples.
+
+ message SingleLabelImageRecord {
+ repeated int32 shape = 1; // it obtains 3 (rgb channels), 32 (row), 32 (col)
+ optional int32 label = 2; // label
+ optional bytes pixel = 3; // pixels
+ repeated float data = 4 [packed = true]; // it is used for normalization
+ }
+
+The data preparation instructions for the [CIFAR-10 image dataset](http://www.cs.toronto.edu/~kriz/cifar.html)
+will be elaborated here. This dataset consists of 60,000 32x32 color images in 10 classes, with 6,000 images per class.
+There are 50,000 training images and 10,000 test images.
+Each image has a single label. This dataset is stored in binary files with specific format.
+SINGA comes with the [create_data.cc](https://github.com/apache/incubator-singa/blob/master/examples/cifar10/create_data.cc)
+to convert images in the binary files into `SingleLabelImageRecord`s and insert them into training and test stores.
+
+1. Download raw data. The following command will download the dataset into *cifar-10-batches-bin* folder.
+
+ # in SINGA_ROOT/examples/cifar10
+ $ cp Makefile.example Makefile // an example makefile is provided
+ $ make download
+
+2. Fill one record for each image, and insert it to store.
+
+ KVFileStore store;
+ store.Open(output_file_path, singa::io::kCreate);
+
+ singa::SingleLabelImageRecord image;
+ for (int image_id = 0; image_id < 50000; image_id ++) {
+ // fill the record with image feature and label from downloaded binay files
+ string str;
+ image.SerializeToString(&str);
+ store.Write(to_string(image_id), str);
+ }
+ store.Flush();
+ store.Close();
+
+ The data store for testing data is created similarly.
+ In addition, it computes average values (not shown here) of image pixels and
+ insert the mean values into a SingleLabelImageRecord, which is then written
+ into a another store.
+
+3. Compile and run the program. SINGA provides an example Makefile that contains instructions
+ for compiling the source code and linking it with *libsinga.so*. Users just execute the following command.
+
+ $ make create
+
+## using user-defined record format
+
+If users cannot use the SingleLabelImageRecord or CSV record for their data.
+They can define their own record format e.g., using Google Protobuf.
+A record can be written into a data store as long as it can be converted
+into byte string. Correspondingly, subclasses of StoreInputLayer are required to
+parse user-defined records.
Added: incubator/singa/site/trunk/content/markdown/docs/kr/debug.md
URL: http://svn.apache.org/viewvc/incubator/singa/site/trunk/content/markdown/docs/kr/debug.md?rev=1724348&view=auto
==============================================================================
--- incubator/singa/site/trunk/content/markdown/docs/kr/debug.md (added)
+++ incubator/singa/site/trunk/content/markdown/docs/kr/debug.md Wed Jan 13 03:46:19 2016
@@ -0,0 +1,29 @@
+# How to Debug
+
+---
+
+Since SINGA is developed on Linux using C++, GDB is the preferred debugging
+tool. To use GDB, the code must be compiled with `-g` flag. This is enabled by
+
+ ./configure --enable-debug
+ make
+
+## Debugging for single process job
+
+If your job launches only one process, then use the default *conf/singa.conf*
+for debugging. The process will be launched locally.
+
+To debug, first start zookeeper if it is not started yet, and launch GDB
+
+ # do this for only once
+ ./bin/zk-service.sh start
+ # do this every time
+ gdb .libs/singa
+
+Then set the command line arguments
+
+ set args -conf JOBCONF
+
+Now you can set your breakpoints and start running.
+
+## Debugging for jobs with multiple processes
Added: incubator/singa/site/trunk/content/markdown/docs/kr/distributed-training.md
URL: http://svn.apache.org/viewvc/incubator/singa/site/trunk/content/markdown/docs/kr/distributed-training.md?rev=1724348&view=auto
==============================================================================
--- incubator/singa/site/trunk/content/markdown/docs/kr/distributed-training.md (added)
+++ incubator/singa/site/trunk/content/markdown/docs/kr/distributed-training.md Wed Jan 13 03:46:19 2016
@@ -0,0 +1,30 @@
+# åæ£ãã¬ã¼ãã³ã°
+
+---
+
+SINGAã¯ã大è¦æ¨¡ãªãã¼ã¿åæã®çºã®å·¨å¤§ãªãã£ã¼ãã©ã¼ãã³ã°ã¢ãã«ã®åæ£ãã¬ã¼ãã³ã°ãç®çã¨ãã¦ãã¶ã¤ã³ããã¦ãã¾ãã
+
+åæ£ãã¬ã¼ãã³ã°ãå¯è½ã¨ããã SINGA ã®ã¢ã¼ããã¯ãã£ã¼ã«é¢ãã詳細ã¯ãä¸ã®ãªã³ã¯ãåç
§ãã¦ãã ããã
+
+* [ã·ã¹ãã ã¢ã¼ããã¯ãã£ã¼](architecture.html)
+
+* [ãã¬ã¼ãã³ã° ãã¬ã¼ã ã¯ã¼ã¯](frameworks.html)
+
+* [ã·ã¹ãã ã³ãã¥ãã±ã¼ã·ã§ã³](communication.html)
+
+ã¢ãã«ã®ãã¬ã¼ãã³ã°ã並ååããããã«ãæ§ã
ãªä¸¦åæ¹æ³ï¼ãã¼ã¿ä¸¦åãã¢ãã«ä¸¦åããã¤ããªãã並åãªã©ï¼ããµãã¼ããã¾ãã
+
+* [ãã¤ããªãã 並åå](hybrid.html)
+
+ç¾å¨ SINGA 㯠Mesos ã¨çµ±åããã¦ããã®ã§ãåæ£ãã¬ã¼ãã³ã°ã Mesos ãã¬ã¼ã ã¯ã¼ã¯ã¨ãã¦å®è¡ã§ãã¾ãã
+Mesos ã¯ã©ã¹ã¿ã¯ãSINGA ã³ã³ããããè¨å®ã§ãã¾ãã
+Mesos 㨠SINGA ããã³ãã«ãã Docker ã¤ã¡ã¼ã¸ãç¨æãã¾ããã
+
+ã¯ã©ã¹ã¿ã®æºåã¨éå§ã«é¢ãã詳細ã¯ãä¸ã®ãªã³ã¯ãåç
§ãã¦ãã ããã
+
+* [Mesos ã§åæ£ãã¬ã¼ãã³ã°](mesos.html)
+
+åæ£ã¹ãã¬ã¼ã¸ã·ã¹ãã ä¸ã§ SINGA ãèµ°ãããã¹ã±ã¼ã©ããªãã£ãä¿è¨¼ãã¾ãã
+ç¾å¨ SINGA 㯠HDFSããµãã¼ããã¦ãã¾ãã
+
+* [HDFS 㧠SINGA ãå®è¡](hdfs.html)
Added: incubator/singa/site/trunk/content/markdown/docs/kr/docker.md
URL: http://svn.apache.org/viewvc/incubator/singa/site/trunk/content/markdown/docs/kr/docker.md?rev=1724348&view=auto
==============================================================================
--- incubator/singa/site/trunk/content/markdown/docs/kr/docker.md (added)
+++ incubator/singa/site/trunk/content/markdown/docs/kr/docker.md Wed Jan 13 03:46:19 2016
@@ -0,0 +1,192 @@
+# Building SINGA Docker container
+
+This guide explains how to set up a development environment for SINGA using Docker. It requires only Docker to be installed. The resulting image contains the complete working environment for SINGA. The image can then be used to set up cluster environment over one or multiple physical nodes.
+
+1. [Build SINGA base](#build_base)
+2. [Build SINGA with Mesos and Hadoop](#build_mesos)
+3. [Pre-built images](#pre_built)
+4. [Launch and stop SINGA (stand alone mode)](#launch_stand_alone)
+5. [Launch pseudo-distributed SINGA on one node](#launch_pseudo)
+6. [Launch fully distributed SINGA on multiple nodes](#launch_distributed)
+
+---
+
+<a name="build_base"></a>
+#### Build SINGA base image
+
+````
+$ cd tool/docker/singa
+$ sudo docker build -t singa/base .
+$ sudo docker images
+REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
+singa/base latest XXXX XXX 2.01 GB
+````
+
+The result is the image containing a built version of SINGA.
+
+ 
+
+ *Figure 1. singa/base Docker image, containing library dependencies and SINGA built from source.*
+
+---
+
+<a name="build_mesos"></a>
+#### Build SINGA with Mesos and Hadoop
+````
+$ cd tool/docker/mesos
+$ sudo docker build -t singa/mesos .
+$ sudo docker images
+REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
+singa/mesos latest XXXX XXX 4.935 GB
+````
+ 
+
+ *Figure 2. singa/mesos Docker image, containing Hadoop and Mesos built on
+top of SINGA. The default namenode address for Hadoop is `node0:9000`*
+
+**Notes** A common failure observed during the build process is caused by network failure occuring when downloading dependencies. Simply re-run the build command.
+
+---
+
+<a name="pre_built"></a>
+#### Pre-built images on epiC cluster
+For users with access to the `epiC` cluster, there are pre-built and loaded Docker images at the following nodes:
+
+ ciidaa-c18
+ ciidaa-c19
+
+The available images at those nodes are:
+
+````
+REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
+singa/base latest XXXX XXX 2.01 GB
+singa/mesos latest XXXX XXX 4.935 GB
+weaveworks/weaveexec 1.1.1 XXXX 11 days ago 57.8 MB
+weaveworks/weave 1.1.1 XXXX 11 days ago 17.56 MB
+````
+
+---
+
+<a name="launch_stand_alone"></a>
+#### Launch and stop SINGA in stand-alone mode
+To launch a test environment for a single-node SINGA training, simply start a container from `singa/base` image. The following starts a container called
+`XYZ`, then launches a shell in the container:
+
+````
+$ sudo docker run -dt --name XYZ singa/base /usr/bin/supervisord
+$ sudo docker exec -it XYZ /bin/bash
+````
+
+
+
+ *Figure 3. Launch SINGA in stand-alone mode: single node training*
+
+Inside the launched container, the SINGA source directory can be found at `/root/incubator-singa`.
+
+**Stopping the container**
+
+````
+$ sudo docker stop XYZ
+$ sudo docker rm ZYZ
+````
+
+---
+
+<a name="launch_pseudo"></a>
+#### Launch SINGA on pseudo-distributed mode (single node)
+To simulate a distributed environment on a single node, one can repeat the
+previous step multiple times, each time giving a different name to the
+container. Network connections between these containers are already supported,
+thus SINGA instances/nodes in these container can readily communicate with each
+other.
+
+The previous approach requires the user to start SINGA instances individually
+at each container. Although there's a bash script for that, we provide a better
+way. In particular, multiple containers can be started from `singa/mesos` image
+which already bundles Mesos and Hadoop with SINGA. Using Mesos makes it easy to
+launch, stop and monitor the distributed execution from a single container.
+Figure 4 shows `N+1` containers running concurrently at the local host.
+
+````
+$ sudo docker run -dt --name node0 singa/mesos /usr/bin/supervisord
+$ sudo docker run -dt --name node1 singa/mesos /usr/bin/supervisord
+...
+````
+
+
+
+*Figure 4. Launch SINGA in pseudo-distributed mode : multiple SINGA nodes over one single machine*
+
+**Starting SINGA distributed training**
+
+Refer to the [Mesos
+guide](mesos.html)
+for details of how to start training with multiple SINGA instances.
+
+**Important:** the container that assumes the role of Hadoop's namenode (and often Mesos's and Zookeeper's mater node as well) **must** be named `node0`. Otherwise, the user must log in to individual containers and change the Hadoop configuration separately.
+
+---
+
+<a name="launch_distributed"></a>
+#### Launch SINGA on fully distributed mode (multiple nodes)
+The previous section has explained how to start a distributed environment on a
+single node. But running many containers on one node does not scale. When there
+are multiple physical hosts available, it is better to distribute the
+containers over them.
+
+The only extra requirement for the fully distributed mode, as compared with the
+pseudo distributed mode, is that the containers from different hosts are able
+to transparently communicate with each other. In the pseudo distributed mode,
+the local docker engine takes care of such communication. Here, we rely on
+[Weave](http://weave.works/guides/weave-docker-ubuntu-simple.html) to make the
+communication transparent. The resulting architecture is shown below.
+
+
+
+*Figure 5. Launch SINGA in fully distributed mode: multiple SINGA nodes over multiple machines*
+
+**Install Weave at all hosts**
+
+```
+$ curl -L git.io/weave -o /usr/local/bin/weave
+$ chmod a+x /usr/local/bin/weave
+```
+
+**Starting Weave**
+
+Suppose `node0` will be launched at host with IP `111.222.111.222`.
+
++ At host `111.222.111.222`:
+
+ $ weave launch
+ $ eval "$(weave env)" //if there's error, do `sudo -s` and try again
+
++ At other hosts:
+
+ $ weave launch 111.222.111.222
+ $ eval "$(weave env)" //if there's error, do `sudo -s` and try again
+
+**Starting containers**
+
+The user logs in to each host and starts the container (same as in [pseudo-distributed](#launch_pseudo) mode). Note that container acting as the head node of the cluster must be named `node0` (and be running at the host with IP `111.222.111.222`, for example).
+
+**_Important_:** when there are other containers sharing the same host as `node0`, say `node1` and `node2` for example,
+there're additional changes to be made to `node1` and `node2`. Particularly, log in to each container and edit
+`/etc/hosts` file:
+
+````
+# modified by weave
+...
+X.Y.Z node0 node0.bridge //<- REMOVE this line
+..
+````
+This is to ensure that name resolutions (of `node0`'s address) from `node1` and `node2` are correct. By default,
+containers of the same host resolves each other's addresses via the Docker bridge. Instead, we want they to use
+addressed given by Weave.
+
+
+**Starting SINGA distributed training**
+
+Refer to the [Mesos guide](mesos.html)
+for details of how to start training with multiple SINGA instances.
+
Added: incubator/singa/site/trunk/content/markdown/docs/kr/examples.md
URL: http://svn.apache.org/viewvc/incubator/singa/site/trunk/content/markdown/docs/kr/examples.md?rev=1724348&view=auto
==============================================================================
--- incubator/singa/site/trunk/content/markdown/docs/kr/examples.md (added)
+++ incubator/singa/site/trunk/content/markdown/docs/kr/examples.md Wed Jan 13 03:46:19 2016
@@ -0,0 +1,29 @@
+# Example Models
+
+---
+
+Different models are provided as examples to help users get familiar with SINGA.
+[Neural Network](neural-net.html) gives details on the models that are
+supported by SINGA.
+
+
+### Feed-forward neural networks
+
+ * [MultiLayer Perceptron](mlp.html) trained on MNIST dataset for handwritten
+ digits recognition.
+
+ * [Convolutional Neural Network](cnn.html) trained on MNIST and CIFAR10 for
+ image classification.
+
+ * [Deep Auto-Encoders](rbm.html) trained on MNIST for dimensionality
+
+
+### Recurrent neural networks (RNN)
+
+ * [RNN language model](rnn.html) trained on plain text for language modelling.
+
+### Energy models
+
+ * [RBM](rbm.html) used to pre-train deep auto-encoders for dimensionality
+ reduction.
+
Added: incubator/singa/site/trunk/content/markdown/docs/kr/frameworks.md
URL: http://svn.apache.org/viewvc/incubator/singa/site/trunk/content/markdown/docs/kr/frameworks.md?rev=1724348&view=auto
==============================================================================
--- incubator/singa/site/trunk/content/markdown/docs/kr/frameworks.md (added)
+++ incubator/singa/site/trunk/content/markdown/docs/kr/frameworks.md Wed Jan 13 03:46:19 2016
@@ -0,0 +1,122 @@
+# Distributed Training Framework
+
+---
+
+## Cluster Topology Configuration
+
+Here we describe how to configure SINGA's cluster topology to support
+different distributed training frameworks.
+The cluster topology is configured in the `cluster` field in `JobProto`.
+The `cluster` is of type `ClusterProto`:
+
+ message ClusterProto {
+ optional int32 nworker_groups = 1;
+ optional int32 nserver_groups = 2;
+ optional int32 nworkers_per_group = 3 [default = 1];
+ optional int32 nservers_per_group = 4 [default = 1];
+ optional int32 nworkers_per_procs = 5 [default = 1];
+ optional int32 nservers_per_procs = 6 [default = 1];
+
+ // servers and workers in different processes?
+ optional bool server_worker_separate = 20 [default = false];
+
+ ......
+ }
+
+
+The mostly used fields are as follows:
+
+ * `nworkers_per_group` and `nworkers_per_procs`:
+ decide the partitioning of worker side ParamShard.
+ * `nservers_per_group` and `nservers_per_procs`:
+ decide the partitioning of server side ParamShard.
+ * `server_worker_separate`:
+ separate servers and workers in different processes.
+
+## Different Training Frameworks
+
+In SINGA, worker groups run asynchronously and
+workers within one group run synchronously.
+Users can leverage this general design to run
+both **synchronous** and **asynchronous** training frameworks.
+Here we illustrate how to configure
+popular distributed training frameworks in SINGA.
+
+<img src="../images/frameworks.png" style="width: 800px"/>
+<p><strong> Fig.1 - Training frameworks in SINGA</strong></p>
+
+###Sandblaster
+
+This is a **synchronous** framework used by Google Brain.
+Fig.2(a) shows the Sandblaster framework implemented in SINGA.
+Its configuration is as follows:
+
+ cluster {
+ nworker_groups: 1
+ nserver_groups: 1
+ nworkers_per_group: 3
+ nservers_per_group: 2
+ server_worker_separate: true
+ }
+
+A single server group is launched to handle all requests from workers.
+A worker computes on its partition of the model,
+and only communicates with servers handling related parameters.
+
+
+###AllReduce
+
+This is a **synchronous** framework used by Baidu's DeepImage.
+Fig.2(b) shows the AllReduce framework implemented in SINGA.
+Its configuration is as follows:
+
+ cluster {
+ nworker_groups: 1
+ nserver_groups: 1
+ nworkers_per_group: 3
+ nservers_per_group: 3
+ server_worker_separate: false
+ }
+
+We bind each worker with a server on the same node, so that each
+node is responsible for maintaining a partition of parameters and
+collecting updates from all other nodes.
+
+###Downpour
+
+This is a **asynchronous** framework used by Google Brain.
+Fig.2(c) shows the Downpour framework implemented in SINGA.
+Its configuration is as follows:
+
+ cluster {
+ nworker_groups: 2
+ nserver_groups: 1
+ nworkers_per_group: 2
+ nservers_per_group: 2
+ server_worker_separate: true
+ }
+
+Similar to the synchronous Sandblaster, all workers send
+requests to a global server group. We divide workers into several
+worker groups, each running independently and working on parameters
+from the last *update* response.
+
+###Distributed Hogwild
+
+This is a **asynchronous** framework used by Caffe.
+Fig.2(d) shows the Distributed Hogwild framework implemented in SINGA.
+Its configuration is as follows:
+
+ cluster {
+ nworker_groups: 3
+ nserver_groups: 3
+ nworkers_per_group: 1
+ nservers_per_group: 1
+ server_worker_separate: false
+ }
+
+Each node contains a complete server group and a complete worker group.
+Parameter updates are done locally, so that communication cost
+during each training step is minimized.
+However, the server group must periodically synchronize with
+neighboring groups to improve the training convergence.
Added: incubator/singa/site/trunk/content/markdown/docs/kr/index.md
URL: http://svn.apache.org/viewvc/incubator/singa/site/trunk/content/markdown/docs/kr/index.md?rev=1724348&view=auto
==============================================================================
--- incubator/singa/site/trunk/content/markdown/docs/kr/index.md (added)
+++ incubator/singa/site/trunk/content/markdown/docs/kr/index.md Wed Jan 13 03:46:19 2016
@@ -0,0 +1,21 @@
+# ìµì 문ì
+
+* [ê°ì](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)
Added: incubator/singa/site/trunk/content/markdown/docs/kr/installation.md
URL: http://svn.apache.org/viewvc/incubator/singa/site/trunk/content/markdown/docs/kr/installation.md?rev=1724348&view=auto
==============================================================================
--- incubator/singa/site/trunk/content/markdown/docs/kr/installation.md (added)
+++ incubator/singa/site/trunk/content/markdown/docs/kr/installation.md Wed Jan 13 03:46:19 2016
@@ -0,0 +1,8 @@
+# ì¸ì¤í¨
+
+---
+
+í기ì 2ê°ì§ ë²ë²ìì ííì¸ì.
+
+* ìì¤ìì ë¹ëã[Build SINGA directly from source](installation_source.html)
+* Docker 컨í
ì´ëì ë¹ë [Build SINGA as a Docker container](docker.html)
Added: incubator/singa/site/trunk/content/markdown/docs/kr/installation_source.md
URL: http://svn.apache.org/viewvc/incubator/singa/site/trunk/content/markdown/docs/kr/installation_source.md?rev=1724348&view=auto
==============================================================================
--- incubator/singa/site/trunk/content/markdown/docs/kr/installation_source.md (added)
+++ incubator/singa/site/trunk/content/markdown/docs/kr/installation_source.md Wed Jan 13 03:46:19 2016
@@ -0,0 +1,249 @@
+# Building SINGA from source
+
+---
+
+## Dependencies
+
+SINGA is developed and tested on Linux platforms.
+
+The following dependent libraries are required:
+
+ * glog version 0.3.3
+
+ * google-protobuf version 2.6.0
+
+ * openblas version >= 0.2.10
+
+ * zeromq version >= 3.2
+
+ * czmq version >= 3
+
+ * zookeeper version 3.4.6
+
+
+Optional dependencies include:
+
+ * lmdb version 0.9.10
+
+
+You can install all dependencies into $PREFIX folder by
+
+ # make sure you are in the thirdparty folder
+ cd thirdparty
+ ./install.sh all $PREFIX
+
+If $PREFIX is not a system path (e.g., /usr/local/), please export the following
+variables to continue the building instructions,
+
+ export LD_LIBRARY_PATH=$PREFIX/lib:$LD_LIBRARY_PATH
+ export CPLUS_INCLUDE_PATH=$PREFIX/include:$CPLUS_INCLUDE_PATH
+ export LIBRARY_PATH=$PREFIX/lib:$LIBRARY_PATH
+ export PATH=$PREFIX/bin:$PATH
+
+More details on using this script is given below.
+
+## Building SINGA from source
+
+SINGA is built using GNU autotools. GCC (version >= 4.8) is required.
+There are two ways to build SINGA,
+
+ * If you want to use the latest code, please clone it from
+ [Github](https://github.com/apache/incubator-singa.git) and execute
+ the following commands,
+
+ $ git clone git@github.com:apache/incubator-singa.git
+ $ cd incubator-singa
+ $ ./autogen.sh
+ $ ./configure
+ $ make
+
+ Note: It is an oversight that we forgot to delete the singa repo under [nusinga](https://github.com/orgs/nusinga)
+ account after we became Apache Incubator project -- the source
+ in that repo was not up to date, and we apologize for any inconvenience.
+
+ * If you download a release package, please follow the instructions below,
+
+ $ tar xvf singa-xxx
+ $ cd singa-xxx
+ $ ./configure
+ $ make
+
+ Some features of SINGA depend on external libraries. These features can be
+ compiled with `--enable-<feature>`.
+ For example, to build SINGA with lmdb support, you can run:
+
+ $ ./configure --enable-lmdb
+
+<!---
+Zhongle: please update the code to use the follow command
+
+ $ make test
+
+After compilation, you will find the binary file singatest. Just run it!
+More details about configure script can be found by running:
+
+ $ ./configure -h
+-->
+
+After compiling SINGA successfully, the *libsinga.so* and the executable file
+*singa* will be generated into *.libs/* folder.
+
+If some dependent libraries are missing (or not detected), you can use the
+following script to download and install them:
+
+<!---
+to be updated after zhongle changes the code to use
+
+ ./install.sh libname \-\-prefix=
+
+-->
+ # must goto thirdparty folder
+ $ cd thirdparty
+ $ ./install.sh LIB_NAME PREFIX
+
+If you do not specify the installation path, the library will be installed in
+the default folder specified by the software itself. For example, if you want
+to install `zeromq` library in the default system folder, run it as
+
+ $ ./install.sh zeromq
+
+Or, if you want to install it into another folder,
+
+ $ ./install.sh zeromq PREFIX
+
+You can also install all dependencies in */usr/local* directory:
+
+ $ ./install.sh all /usr/local
+
+Here is a table showing the first arguments:
+
+ LIB_NAME LIBRARIE
+ czmq* czmq lib
+ glog glog lib
+ lmdb lmdb lib
+ OpenBLAS OpenBLAS lib
+ protobuf Google protobuf
+ zeromq zeromq lib
+ zookeeper Apache zookeeper
+
+*: Since `czmq` depends on `zeromq`, the script offers you one more argument to
+indicate `zeromq` location.
+The installation commands of `czmq` is:
+
+<!---
+to be updated to
+
+ $./install.sh czmq \-\-prefix=/usr/local \-\-zeromq=/usr/local/zeromq
+-->
+
+ $./install.sh czmq /usr/local -f=/usr/local/zeromq
+
+After the execution, `czmq` will be installed in */usr/local*. The last path
+specifies the path to zeromq.
+
+### FAQ
+* Q1:I get error `./configure --> cannot find blas_segmm() function` even I
+have installed OpenBLAS.
+
+ A1: This means the compiler cannot find the `OpenBLAS` library. If you installed
+ it to $PREFIX (e.g., /opt/OpenBLAS), then you need to export it as
+
+ $ export LIBRARY_PATH=$PREFIX/lib:$LIBRARY_PATH
+ # e.g.,
+ $ export LIBRARY_PATH=/opt/OpenBLAS/lib:$LIBRARY_PATH
+
+
+* Q2: I get error `cblas.h no such file or directory exists`.
+
+ Q2: You need to include the folder of the cblas.h into CPLUS_INCLUDE_PATH,
+ e.g.,
+
+ $ export CPLUS_INCLUDE_PATH=$PREFIX/include:$CPLUS_INCLUDE_PATH
+ # e.g.,
+ $ export CPLUS_INCLUDE_PATH=/opt/OpenBLAS/include:$CPLUS_INCLUDE_PATH
+ # then reconfigure and make SINGA
+ $ ./configure
+ $ make
+
+
+* Q3:While compiling SINGA, I get error `SSE2 instruction set not enabled`
+
+ A3:You can try following command:
+
+ $ make CFLAGS='-msse2' CXXFLAGS='-msse2'
+
+
+* Q4:I get `ImportError: cannot import name enum_type_wrapper` from
+google.protobuf.internal when I try to import .py files.
+
+ A4:After install google protobuf by `make install`, we should install python
+ runtime libraries. Go to protobuf source directory, run:
+
+ $ cd /PROTOBUF/SOURCE/FOLDER
+ $ cd python
+ $ python setup.py build
+ $ python setup.py install
+
+ You may need `sudo` when you try to install python runtime libraries in
+ the system folder.
+
+
+* Q5: I get a linking error caused by gflags.
+
+ A5: SINGA does not depend on gflags. But you may have installed the glog with
+ gflags. In that case you can reinstall glog using *thirdparty/install.sh* into
+ a another folder and export the LDFLAGS and CPPFLAGS to include that folder.
+
+
+* Q6: While compiling SINGA and installing `glog` on mac OS X, I get fatal error
+`'ext/slist' file not found`
+
+ A6:Please install `glog` individually and try :
+
+ $ make CFLAGS='-stdlib=libstdc++' CXXFLAGS='stdlib=libstdc++'
+
+* Q7: When I start a training job, it reports error related with "ZOO_ERROR...zk retcode=-4...".
+
+ A7: This is because the zookeeper is not started. Please start the zookeeper service
+
+ $ ./bin/zk-service start
+
+ If the error still exists, probably that you do not have java. You can simple
+ check it by
+
+ $ java --version
+
+* Q8: When I build OpenBLAS from source, I am told that I need a fortran compiler.
+
+ A8: You can compile OpenBLAS by
+
+ $ make ONLY_CBLAS=1
+
+ or install it using
+
+ $ sudo apt-get install openblas-dev
+
+ or
+
+ $ sudo yum install openblas-devel
+
+ It is worth noting that you need root access to run the last two commands.
+ Remember to set the environment variables to include the header and library
+ paths of OpenBLAS after installation (please refer to the Dependencies section).
+
+* Q9: When I build protocol buffer, it reports that GLIBC++_3.4.20 not found in /usr/lib64/libstdc++.so.6.
+
+ A9: This means the linker found libstdc++.so.6 but that library
+ belongs to an older version of GCC than was used to compile and link the
+ program. The program depends on code defined in
+ the newer libstdc++ that belongs to the newer version of GCC, so the linker
+ must be told how to find the newer libstdc++ shared library.
+ The simplest way to fix this is to find the correct libstdc++ and export it to
+ LD_LIBRARY_PATH. For example, if GLIBC++_3.4.20 is listed in the output of the
+ following command,
+
+ $ strings /usr/local/lib64/libstdc++.so.6|grep GLIBC++
+
+ then you just set your environment variable as
+
+ $ export LD_LIBRARY_PATH=/usr/local/lib64:$LD_LIBRARY_PATH
Added: incubator/singa/site/trunk/content/markdown/docs/kr/layer.md
URL: http://svn.apache.org/viewvc/incubator/singa/site/trunk/content/markdown/docs/kr/layer.md?rev=1724348&view=auto
==============================================================================
--- incubator/singa/site/trunk/content/markdown/docs/kr/layer.md (added)
+++ incubator/singa/site/trunk/content/markdown/docs/kr/layer.md Wed Jan 13 03:46:19 2016
@@ -0,0 +1,614 @@
+# Layers
+
+---
+
+Layer is a core abstraction in SINGA. It performs a variety of feature
+transformations for extracting high-level features, e.g., loading raw features,
+parsing RGB values, doing convolution transformation, etc.
+
+The *Basic user guide* section introduces the configuration of a built-in
+layer. *Advanced user guide* explains how to extend the base Layer class to
+implement users' functions.
+
+## Basic user guide
+
+### Layer configuration
+
+Configuration of two example layers are shown below,
+
+ layer {
+ name: "data"
+ type: kCSVRecord
+ store_conf { }
+ }
+ layer{
+ name: "fc1"
+ type: kInnerProduct
+ srclayers: "data"
+ innerproduct_conf{ }
+ param{ }
+ }
+
+There are some common fields for all kinds of layers:
+
+ * `name`: a string used to differentiate two layers in a neural net.
+ * `type`: an integer used for identifying a specific Layer subclass. The types of built-in
+ layers are listed in LayerType (defined in job.proto).
+ For user-defined layer subclasses, `user_type` should be used instead of `type`.
+ * `srclayers`: names of the source layers.
+ In SINGA, all connections are [converted](neural-net.html) to directed connections.
+ * `param`: configuration for a [Param](param.html) instance.
+ There can be multiple Param objects in one layer.
+
+Different layers may have different configurations. These configurations
+are defined in `<type>_conf`. E.g., "fc1" layer has
+`innerproduct_conf`. The subsequent sections
+explain the functionality of each built-in layer and how to configure it.
+
+### Built-in Layer subclasses
+SINGA has provided many built-in layers, which can be used directly to create neural nets.
+These layers are categorized according to their functionalities,
+
+ * Input layers for loading records (e.g., images) from disk files, HDFS or network into memory.
+ * Neuron layers for feature transformation, e.g., [convolution](../api/classsinga_1_1ConvolutionLayer.html), [pooling](../api/classsinga_1_1PoolingLayer.html), dropout, etc.
+ * Loss layers for measuring the training objective loss, e.g., Cross Entropy loss or Euclidean loss.
+ * Output layers for outputting the prediction results (e.g., probabilities of each category) or features into persistent storage, e.g., disk or HDFS.
+ * Connection layers for connecting layers when the neural net is partitioned.
+
+#### Input layers
+
+Input layers load training/test data from disk or other places (e.g., HDFS or network)
+into memory.
+
+##### StoreInputLayer
+
+[StoreInputLayer](../api/classsinga_1_1StoreInputLayer.html) is a base layer for
+loading data from data store. The data store can be a KVFile or TextFile (LMDB,
+LevelDB, HDFS, etc., will be supported later). Its `ComputeFeature` function reads
+batchsize (string:key, string:value) tuples. Each tuple is parsed by a `Parse` function
+implemented by its subclasses.
+
+The configuration for this layer is in `store_conf`,
+
+ store_conf {
+ backend: # "kvfile" or "textfile"
+ path: # path to the data store
+ batchsize :
+ ...
+ }
+
+##### SingleLabelRecordLayer
+
+It is a subclass of StoreInputLayer. It assumes the (key, value) tuple loaded
+from a data store contains a feature vector (and a label) for one data instance.
+All feature vectors are of the same fixed length. The shape of one instance
+is configured through the `shape` field, e.g., the following configuration
+specifies the shape for the CIFAR10 images.
+
+ store_conf {
+ shape: 3 #channels
+ shape: 32 #height
+ shape: 32 #width
+ }
+
+It may do some preprocessing like [standardization](http://ufldl.stanford.edu/wiki/index.php/Data_Preprocessing).
+The data for preprocessing is loaded by and parsed in a virtual function, which is implemented by
+its subclasses.
+
+##### RecordInputLayer
+
+It is a subclass of SingleLabelRecordLayer. It parses the value field from one
+tuple into a RecordProto, which is generated by Google Protobuf according
+to common.proto. It can be used to store features for images (e.g., using the pixel field)
+or other objects (using the data field). The key field is not parsed.
+
+ type: kRecordInput
+ store_conf {
+ has_label: # default is true
+ ...
+ }
+
+##### CSVInputLayer
+
+It is a subclass of SingleLabelRecordLayer. The value field from one tuple is parsed
+as a CSV line (separated by comma). The first number would be parsed as a label if
+`has_label` is configured in `store_conf`. Otherwise, all numbers would be parsed
+into one row of the `data_` Blob.
+
+ type: kCSVInput
+ store_conf {
+ has_label: # default is true
+ ...
+ }
+
+##### ImagePreprocessLayer
+
+This layer does image preprocessing, e.g., cropping, mirroring and scaling, against
+the data Blob from its source layer. It deprecates the RGBImageLayer which
+works on the Record from ShardDataLayer. It still uses the same configuration as
+RGBImageLayer,
+
+ type: kImagePreprocess
+ rgbimage_conf {
+ scale: float
+ cropsize: int # cropping each image to keep the central part with this size
+ mirror: bool # mirror the image by set image[i,j]=image[i,len-j]
+ meanfile: "Image_Mean_File_Path"
+ }
+
+##### ShardDataLayer (Deprected)
+Deprected! Please use ProtoRecordInputLayer or CSVRecordInputLayer.
+
+[ShardDataLayer](../api/classsinga_1_1ShardDataLayer.html) is a subclass of DataLayer,
+which reads Records from disk file. The file should be created using
+[DataShard](../api/classsinga_1_1DataShard.html)
+class. With the data file prepared, users configure the layer as
+
+ type: kShardData
+ sharddata_conf {
+ path: "path to data shard folder"
+ batchsize: int
+ random_skip: int
+ }
+
+`batchsize` specifies the number of records to be trained for one mini-batch.
+The first `rand() % random_skip` `Record`s will be skipped at the first
+iteration. This is to enforce that different workers work on different Records.
+
+##### LMDBDataLayer (Deprected)
+Deprected! Please use ProtoRecordInputLayer or CSVRecordInputLayer.
+
+[LMDBDataLayer] is similar to ShardDataLayer, except that the Records are
+loaded from LMDB.
+
+ type: kLMDBData
+ lmdbdata_conf {
+ path: "path to LMDB folder"
+ batchsize: int
+ random_skip: int
+ }
+
+##### ParserLayer (Deprected)
+Deprected! Please use ProtoRecordInputLayer or CSVRecordInputLayer.
+
+It get a vector of Records from DataLayer and parse features into
+a Blob.
+
+ virtual void ParseRecords(Phase phase, const vector<Record>& records, Blob<float>* blob) = 0;
+
+
+##### LabelLayer (Deprected)
+Deprected! Please use ProtoRecordInputLayer or CSVRecordInputLayer.
+
+[LabelLayer](../api/classsinga_1_1LabelLayer.html) is a subclass of ParserLayer.
+It parses a single label from each Record. Consequently, it
+will put $b$ (mini-batch size) values into the Blob. It has no specific configuration fields.
+
+
+##### MnistImageLayer (Deprected)
+Deprected! Please use ProtoRecordInputLayer or CSVRecordInputLayer.
+[MnistImageLayer] is a subclass of ParserLayer. It parses the pixel values of
+each image from the MNIST dataset. The pixel
+values may be normalized as `x/norm_a - norm_b`. For example, if `norm_a` is
+set to 255 and `norm_b` is set to 0, then every pixel will be normalized into
+[0, 1].
+
+ type: kMnistImage
+ mnistimage_conf {
+ norm_a: float
+ norm_b: float
+ }
+
+##### RGBImageLayer (Deprected)
+Deprected! Please use the ImagePreprocessLayer.
+[RGBImageLayer](../api/classsinga_1_1RGBImageLayer.html) is a subclass of ParserLayer.
+It parses the RGB values of one image from each Record. It may also
+apply some transformations, e.g., cropping, mirroring operations. If the
+`meanfile` is specified, it should point to a path that contains one Record for
+the mean of each pixel over all training images.
+
+ type: kRGBImage
+ rgbimage_conf {
+ scale: float
+ cropsize: int # cropping each image to keep the central part with this size
+ mirror: bool # mirror the image by set image[i,j]=image[i,len-j]
+ meanfile: "Image_Mean_File_Path"
+ }
+
+##### PrefetchLayer
+
+[PrefetchLayer](../api/classsinga_1_1PrefetchLayer.html) embeds other input layers
+to do data prefeching. It will launch a thread to call the embedded layers to load and extract features.
+It ensures that the I/O task and computation task can work simultaneously.
+One example PrefetchLayer configuration is,
+
+ layer {
+ name: "prefetch"
+ type: kPrefetch
+ sublayers {
+ name: "data"
+ type: kShardData
+ sharddata_conf { }
+ }
+ sublayers {
+ name: "rgb"
+ type: kRGBImage
+ srclayers:"data"
+ rgbimage_conf { }
+ }
+ sublayers {
+ name: "label"
+ type: kLabel
+ srclayers: "data"
+ }
+ exclude:kTest
+ }
+
+The layers on top of the PrefetchLayer should use the name of the embedded
+layers as their source layers. For example, the "rgb" and "label" should be
+configured to the `srclayers` of other layers.
+
+
+#### Output Layers
+
+Output layers get data from their source layers and write them to persistent storage,
+e.g., disk files or HDFS (to be supported).
+
+##### RecordOutputLayer
+
+This layer gets data (and label if it is available) from its source layer and converts it into records of type
+RecordProto. Records are written as (key = instance No., value = serialized record) tuples into Store, e.g., KVFile. The configuration of this layer
+should include the specifics of the Store backend via `store_conf`.
+
+ layer {
+ name: "output"
+ type: kRecordOutput
+ srclayers:
+ store_conf {
+ backend: "kvfile"
+ path:
+ }
+ }
+
+##### CSVOutputLayer
+This layer gets data (and label if it available) from its source layer and converts it into
+a string per instance with fields separated by commas (i.e., CSV format). The shape information
+is not kept in the string. All strings are written into
+Store, e.g., text file. The configuration of this layer should include the specifics of the Store backend via `store_conf`.
+
+ layer {
+ name: "output"
+ type: kCSVOutput
+ srclayers:
+ store_conf {
+ backend: "textfile"
+ path:
+ }
+ }
+
+#### Neuron Layers
+
+Neuron layers conduct feature transformations.
+
+##### ConvolutionLayer
+
+[ConvolutionLayer](../api/classsinga_1_1ConvolutionLayer.html) conducts convolution transformation.
+
+ type: kConvolution
+ convolution_conf {
+ num_filters: int
+ kernel: int
+ stride: int
+ pad: int
+ }
+ param { } # weight/filter matrix
+ param { } # bias vector
+
+The int value `num_filters` stands for the count of the applied filters; the int
+value `kernel` stands for the convolution kernel size (equal width and height);
+the int value `stride` stands for the distance between the successive filters;
+the int value `pad` pads each with a given int number of pixels border of
+zeros.
+
+##### InnerProductLayer
+
+[InnerProductLayer](../api/classsinga_1_1InnerProductLayer.html) is fully connected with its (single) source layer.
+Typically, it has two parameter fields, one for weight matrix, and the other
+for bias vector. It rotates the feature of the source layer (by multiplying with weight matrix) and
+shifts it (by adding the bias vector).
+
+ type: kInnerProduct
+ innerproduct_conf {
+ num_output: int
+ }
+ param { } # weight matrix
+ param { } # bias vector
+
+
+##### PoolingLayer
+
+[PoolingLayer](../api/classsinga_1_1PoolingLayer.html) is used to do a normalization (or averaging or sampling) of the
+feature vectors from the source layer.
+
+ type: kPooling
+ pooling_conf {
+ pool: AVE|MAX // Choose whether use the Average Pooling or Max Pooling
+ kernel: int // size of the kernel filter
+ pad: int // the padding size
+ stride: int // the step length of the filter
+ }
+
+The pooling layer has two methods: Average Pooling and Max Pooling.
+Use the enum AVE and MAX to choose the method.
+
+ * Max Pooling selects the max value for each filtering area as a point of the
+ result feature blob.
+ * Average Pooling averages all values for each filtering area at a point of the
+ result feature blob.
+
+##### ReLULayer
+
+[ReLuLayer](../api/classsinga_1_1ReLULayer.html) has rectified linear neurons, which conducts the following
+transformation, `f(x) = Max(0, x)`. It has no specific configuration fields.
+
+##### STanhLayer
+
+[STanhLayer](../api/classsinga_1_1TanhLayer.html) uses the scaled tanh as activation function, i.e., `f(x)=1.7159047* tanh(0.6666667 * x)`.
+It has no specific configuration fields.
+
+##### SigmoidLayer
+
+[SigmoidLayer] uses the sigmoid (or logistic) as activation function, i.e.,
+`f(x)=sigmoid(x)`. It has no specific configuration fields.
+
+
+##### Dropout Layer
+[DropoutLayer](../api/asssinga_1_1DropoutLayer.html) is a layer that randomly dropouts some inputs.
+This scheme helps deep learning model away from over-fitting.
+
+ type: kDropout
+ dropout_conf {
+ dropout_ratio: float # dropout probability
+ }
+
+##### LRNLayer
+[LRNLayer](../api/classsinga_1_1LRNLayer.html), (Local Response Normalization), normalizes over the channels.
+
+ type: kLRN
+ lrn_conf {
+ local_size: int
+ alpha: float // scaling parameter
+ beta: float // exponential number
+ }
+
+`local_size` specifies the quantity of the adjoining channels which will be summed up.
+ For `WITHIN_CHANNEL`, it means the side length of the space region which will be summed up.
+
+
+#### Loss Layers
+
+Loss layers measures the objective training loss.
+
+##### SoftmaxLossLayer
+
+[SoftmaxLossLayer](../api/classsinga_1_1SoftmaxLossLayer.html) is a combination of the Softmax transformation and
+Cross-Entropy loss. It applies Softmax firstly to get a prediction probability
+for each output unit (neuron) and compute the cross-entropy against the ground truth.
+It is generally used as the final layer to generate labels for classification tasks.
+
+ type: kSoftmaxLoss
+ softmaxloss_conf {
+ topk: int
+ }
+
+The configuration field `topk` is for selecting the labels with `topk`
+probabilities as the prediction results. It is tedious for users to view the
+prediction probability of every label.
+
+#### ConnectionLayer
+
+Subclasses of ConnectionLayer are utility layers that connects other layers due
+to neural net partitioning or other cases.
+
+##### ConcateLayer
+
+[ConcateLayer](../api/classsinga_1_1ConcateLayer.html) connects more than one source layers to concatenate their feature
+blob along given dimension.
+
+ type: kConcate
+ concate_conf {
+ concate_dim: int // define the dimension
+ }
+
+##### SliceLayer
+
+[SliceLayer](../api/classsinga_1_1SliceLayer.html) connects to more than one destination layers to slice its feature
+blob along given dimension.
+
+ type: kSlice
+ slice_conf {
+ slice_dim: int
+ }
+
+##### SplitLayer
+
+[SplitLayer](../api/classsinga_1_1SplitLayer.html) connects to more than one destination layers to replicate its
+feature blob.
+
+ type: kSplit
+ split_conf {
+ num_splits: int
+ }
+
+##### BridgeSrcLayer & BridgeDstLayer
+
+[BridgeSrcLayer](../api/classsinga_1_1BridgeSrcLayer.html) &
+[BridgeDstLayer](../api/classsinga_1_1BridgeDstLayer.html) are utility layers assisting data (e.g., feature or
+gradient) transferring due to neural net partitioning. These two layers are
+added implicitly. Users typically do not need to configure them in their neural
+net configuration.
+
+### OutputLayer
+
+It write the prediction results or the extracted features into file, HTTP stream
+or other places. Currently SINGA has not implemented any specific output layer.
+
+## Advanced user guide
+
+The base Layer class is introduced in this section, followed by how to
+implement a new Layer subclass.
+
+### Base Layer class
+
+#### Members
+
+ LayerProto layer_conf_;
+ Blob<float> data_, grad_;
+ vector<AuxType> aux_data_;
+
+The base layer class keeps the user configuration in `layer_conf_`.
+Almost all layers has $b$ (mini-batch size) feature vectors, which are stored
+in the `data_` [Blob](../api/classsinga_1_1Blob.html) (A Blob is a chunk of memory space, proposed in
+[Caffe](http://caffe.berkeleyvision.org/)).
+There are layers without feature vectors; instead, they share the data from
+source layers.
+The `grad_` Blob is for storing the gradients of the
+objective loss w.r.t. the `data_` Blob. It is necessary in [BP algorithm](../api/classsinga_1_1BPWorker.html),
+hence we put it as a member of the base class. For [CD algorithm](../api/classsinga_1_1CDWorker.html), the `grad_`
+field is not used; instead, the layers for the RBM model may have a Blob for the positive
+phase feature and a Blob for the negative phase feature. For a recurrent layer
+in RNN, one row of the feature blob corresponds to the feature of one internal layer.
+The `aux_data_` stores the auxiliary data, e.g., image label (set `AuxType` to int).
+If images have variant number of labels, the AuxType can be defined to `vector<int>`.
+Currently, we hard code `AuxType` to int. It will be added as a template argument of Layer class later.
+
+If a layer has parameters, these parameters are declared using type
+[Param](param.html). Since some layers do not have
+parameters, we do not declare any `Param` in the base layer class.
+
+#### Functions
+
+ virtual void Setup(const LayerProto& conf, const vector<Layer*>& srclayers);
+ virtual void ComputeFeature(int flag, const vector<Layer*>& srclayers) = 0;
+ virtual void ComputeGradient(int flag, const vector<Layer*>& srclayers) = 0;
+
+The `Setup` function reads user configuration, i.e. `conf`, and information
+from source layers, e.g., mini-batch size, to set the
+shape of the `data_` (and `grad_`) field as well
+as some other layer specific fields.
+<!---
+If `npartitions` is larger than 1, then
+users need to reduce the sizes of `data_`, `grad_` Blobs or Param objects. For
+example, if the `partition_dim=0` and there is no source layer, e.g., this
+layer is a (bottom) data layer, then its `data_` and `grad_` Blob should have
+`b/npartitions` feature vectors; If the source layer is also partitioned on
+dimension 0, then this layer should have the same number of feature vectors as
+the source layer. More complex partition cases are discussed in
+[Neural net partitioning](neural-net.html#neural-net-partitioning). Typically, the
+Setup function just set the shapes of `data_` Blobs and Param objects.
+-->
+Memory will not be allocated until computation over the data structure happens.
+
+The `ComputeFeature` function evaluates the feature blob by transforming (e.g.
+convolution and pooling) features from the source layers. `ComputeGradient`
+computes the gradients of parameters associated with this layer. These two
+functions are invoked by the [TrainOneBatch](train-one-batch.html)
+function during training. Hence, they should be consistent with the
+`TrainOneBatch` function. Particularly, for feed-forward and RNN models, they are
+trained using [BP algorithm](train-one-batch.html#back-propagation),
+which requires each layer's `ComputeFeature`
+function to compute `data_` based on source layers, and requires each layer's
+`ComputeGradient` to compute gradients of parameters and source layers'
+`grad_`. For energy models, e.g., RBM, they are trained by
+[CD algorithm](train-one-batch.html#contrastive-divergence), which
+requires each layer's `ComputeFeature` function to compute the feature vectors
+for the positive phase or negative phase depending on the `phase` argument, and
+requires the `ComputeGradient` function to only compute parameter gradients.
+For some layers, e.g., loss layer or output layer, they can put the loss or
+prediction result into the `metric` argument, which will be averaged and
+displayed periodically.
+
+### Implementing a new Layer subclass
+
+Users can extend the Layer class or other subclasses to implement their own feature transformation
+logics as long as the two virtual functions are overridden to be consistent with
+the `TrainOneBatch` function. The `Setup` function may also be overridden to
+read specific layer configuration.
+
+The [RNNLM](rnn.html) provides a couple of user-defined layers. You can refer to them as examples.
+
+#### Layer specific protocol message
+
+To implement a new layer, the first step is to define the layer specific
+configuration. Suppose the new layer is `FooLayer`, the layer specific
+google protocol message `FooLayerProto` should be defined as
+
+ # in user.proto
+ package singa
+ import "job.proto"
+ message FooLayerProto {
+ optional int32 a = 1; // specific fields to the FooLayer
+ }
+
+In addition, users need to extend the original `LayerProto` (defined in job.proto of SINGA)
+to include the `foo_conf` as follows.
+
+ extend LayerProto {
+ optional FooLayerProto foo_conf = 101; // unique field id, reserved for extensions
+ }
+
+If there are multiple new layers, then each layer that has specific
+configurations would have a `<type>_conf` field and takes one unique extension number.
+SINGA has reserved enough extension numbers, e.g., starting from 101 to 1000.
+
+ # job.proto of SINGA
+ LayerProto {
+ ...
+ extensions 101 to 1000;
+ }
+
+With user.proto defined, users can use
+[protoc](https://developers.google.com/protocol-buffers/) to generate the `user.pb.cc`
+and `user.pb.h` files. In users' code, the extension fields can be accessed via,
+
+ auto conf = layer_proto_.GetExtension(foo_conf);
+ int a = conf.a();
+
+When defining configurations of the new layer (in job.conf), users should use
+`user_type` for its layer type instead of `type`. In addition, `foo_conf`
+should be enclosed in brackets.
+
+ layer {
+ name: "foo"
+ user_type: "kFooLayer" # Note user_type of user-defined layers is string
+ [foo_conf] { # Note there is a pair of [] for extension fields
+ a: 10
+ }
+ }
+
+#### New Layer subclass declaration
+
+The new layer subclass can be implemented like the built-in layer subclasses.
+
+ class FooLayer : public singa::Layer {
+ public:
+ void Setup(const LayerProto& conf, const vector<Layer*>& srclayers) override;
+ void ComputeFeature(int flag, const vector<Layer*>& srclayers) override;
+ void ComputeGradient(int flag, const vector<Layer*>& srclayers) override;
+
+ private:
+ // members
+ };
+
+Users must override the two virtual functions to be called by the
+`TrainOneBatch` for either BP or CD algorithm. Typically, the `Setup` function
+will also be overridden to initialize some members. The user configured fields
+can be accessed through `layer_conf_` as shown in the above paragraphs.
+
+#### New Layer subclass registration
+
+The newly defined layer should be registered in [main.cc](http://singa.incubator.apache.org/docs/programming-guide) by adding
+
+ driver.RegisterLayer<FooLayer, std::string>("kFooLayer"); // "kFooLayer" should be matched to layer configurations in job.conf.
+
+After that, the [NeuralNet](neural-net.html) can create instances of the new Layer subclass.
Added: incubator/singa/site/trunk/content/markdown/docs/kr/lmdb.md
URL: http://svn.apache.org/viewvc/incubator/singa/site/trunk/content/markdown/docs/kr/lmdb.md?rev=1724348&view=auto
==============================================================================
(empty)
Added: incubator/singa/site/trunk/content/markdown/docs/kr/mesos.md
URL: http://svn.apache.org/viewvc/incubator/singa/site/trunk/content/markdown/docs/kr/mesos.md?rev=1724348&view=auto
==============================================================================
--- incubator/singa/site/trunk/content/markdown/docs/kr/mesos.md (added)
+++ incubator/singa/site/trunk/content/markdown/docs/kr/mesos.md Wed Jan 13 03:46:19 2016
@@ -0,0 +1,84 @@
+#Distributed Training on Mesos
+
+This guide explains how to start SINGA distributed training on a Mesos cluster. It assumes that both Mesos and HDFS are already running, and every node has SINGA installed.
+We assume the architecture depicted below, in which a cluster nodes are Docker container. Refer to [Docker guide](docker.html) for details of how to start individual nodes and set up network connection between them (make sure [weave](http://weave.works/guides/weave-docker-ubuntu-simple.html) is running at each node, and the cluster's headnode is running in container `node0`)
+
+
+
+---
+
+## Start HDFS and Mesos
+Go inside each container, using:
+````
+docker exec -it nodeX /bin/bash
+````
+and configure it as follows:
+
+* On container `node0`
+
+ hadoop namenode -format
+ hadoop-daemon.sh start namenode
+ /opt/mesos-0.22.0/build/bin/mesos-master.sh --work_dir=/opt --log_dir=/opt --quiet > /dev/null &
+ zk-service.sh start
+
+* On container `node1, node2, ...`
+
+ hadoop-daemon.sh start datanode
+ /opt/mesos-0.22.0/build/bin/mesos-slave.sh --master=node0:5050 --log_dir=/opt --quiet > /dev/null &
+
+To check if the setup has been successful, check that HDFS namenode has registered `N` datanodes, via:
+
+````
+hadoop dfsadmin -report
+````
+
+#### Mesos logs
+Mesos logs are stored at `/opt/lt-mesos-master.INFO` on `node0` and `/opt/lt-mesos-slave.INFO` at other nodes.
+
+---
+
+## Starting SINGA training on Mesos
+Assumed that Mesos and HDFS are already started, SINGA job can be launched at **any** container.
+
+#### Launching job
+
+1. Log in to any container, then
+ cd incubator-singa/tool/mesos
+<a name="job_start"></a>
+2. Check that configuration files are correct:
+ + `scheduler.conf` contains information about the master nodes
+ + `singa.conf` contains information about Zookeeper node0
+ + Job configuration file `job.conf` **contains full path to the examples directories (NO RELATIVE PATH!).**
+3. Start the job:
+ + If starting for the first time:
+
+ ./scheduler <job config file> -scheduler_conf <scheduler config file> -singa_conf <SINGA config file>
+ + If not the first time:
+
+ ./scheduler <job config file>
+
+**Notes.** Each running job is given a `frameworkID`. Look for the log message of the form:
+
+ Framework registered with XXX-XXX-XXX-XXX-XXX-XXX
+
+#### Monitoring and Debugging
+
+Each Mesos job is given a `frameworkID` and a *sandbox* directory is created for each job.
+The directory is in the specified `work_dir` (or `/tmp/mesos`) by default. For example, the error
+during SINGA execution can be found at:
+
+ /tmp/mesos/slaves/xxxxx-Sx/frameworks/xxxxx/executors/SINGA_x/runs/latest/stderr
+
+Other artifacts, like files downloaded from HDFS (`job.conf`) and `stdout` can be found in the same
+directory.
+
+#### Stopping
+
+There are two way to kill the running job:
+
+1. If the scheduler is running in the foreground, simply kill it (using `Ctrl-C`, for example).
+
+2. If the scheduler is running in the background, kill it using Mesos's REST API:
+
+ curl -d "frameworkId=XXX-XXX-XXX-XXX-XXX-XXX" -X POST http://<master>/master/shutdown
+
Added: incubator/singa/site/trunk/content/markdown/docs/kr/mlp.md
URL: http://svn.apache.org/viewvc/incubator/singa/site/trunk/content/markdown/docs/kr/mlp.md?rev=1724348&view=auto
==============================================================================
--- incubator/singa/site/trunk/content/markdown/docs/kr/mlp.md (added)
+++ incubator/singa/site/trunk/content/markdown/docs/kr/mlp.md Wed Jan 13 03:46:19 2016
@@ -0,0 +1,195 @@
+# MLP Example
+
+---
+
+Multilayer perceptron (MLP) is a subclass of feed-forward neural networks.
+A MLP typically consists of multiple directly connected layers, with each layer fully
+connected to the next one. In this example, we will use SINGA to train a
+[simple MLP model proposed by Ciresan](http://arxiv.org/abs/1003.0358)
+for classifying handwritten digits from the [MNIST dataset](http://yann.lecun.com/exdb/mnist/).
+
+## Running instructions
+
+Please refer to the [installation](installation.html) page for
+instructions on building SINGA, and the [quick start](quick-start.html)
+for instructions on starting zookeeper.
+
+We have provided scripts for preparing the training and test dataset in *examples/cifar10/*.
+
+ # in examples/mnist
+ $ cp Makefile.example Makefile
+ $ make download
+ $ make create
+
+After the datasets are prepared, we start the training by
+
+ ./bin/singa-run.sh -conf examples/mnist/job.conf
+
+After it is started, you should see output like
+
+ Record job information to /tmp/singa-log/job-info/job-1-20150817-055231
+ Executing : ./singa -conf /xxx/incubator-singa/examples/mnist/job.conf -singa_conf /xxx/incubator-singa/conf/singa.conf -singa_job 1
+ E0817 07:15:09.211885 34073 cluster.cc:51] proc #0 -> 192.168.5.128:49152 (pid = 34073)
+ E0817 07:15:14.972231 34114 server.cc:36] Server (group = 0, id = 0) start
+ E0817 07:15:14.972520 34115 worker.cc:134] Worker (group = 0, id = 0) start
+ E0817 07:15:24.462602 34073 trainer.cc:373] Test step-0, loss : 2.341021, accuracy : 0.109100
+ E0817 07:15:47.341076 34073 trainer.cc:373] Train step-0, loss : 2.357269, accuracy : 0.099000
+ E0817 07:16:07.173364 34073 trainer.cc:373] Train step-10, loss : 2.222740, accuracy : 0.201800
+ E0817 07:16:26.714855 34073 trainer.cc:373] Train step-20, loss : 2.091030, accuracy : 0.327200
+ E0817 07:16:46.590946 34073 trainer.cc:373] Train step-30, loss : 1.969412, accuracy : 0.442100
+ E0817 07:17:06.207080 34073 trainer.cc:373] Train step-40, loss : 1.865466, accuracy : 0.514800
+ E0817 07:17:25.890033 34073 trainer.cc:373] Train step-50, loss : 1.773849, accuracy : 0.569100
+ E0817 07:17:51.208935 34073 trainer.cc:373] Test step-60, loss : 1.613709, accuracy : 0.662100
+ E0817 07:17:53.176766 34073 trainer.cc:373] Train step-60, loss : 1.659150, accuracy : 0.652600
+ E0817 07:18:12.783370 34073 trainer.cc:373] Train step-70, loss : 1.574024, accuracy : 0.666000
+ E0817 07:18:32.904942 34073 trainer.cc:373] Train step-80, loss : 1.529380, accuracy : 0.670500
+ E0817 07:18:52.608111 34073 trainer.cc:373] Train step-90, loss : 1.443911, accuracy : 0.703500
+ E0817 07:19:12.168465 34073 trainer.cc:373] Train step-100, loss : 1.387759, accuracy : 0.721000
+ E0817 07:19:31.855865 34073 trainer.cc:373] Train step-110, loss : 1.335246, accuracy : 0.736500
+ E0817 07:19:57.327133 34073 trainer.cc:373] Test step-120, loss : 1.216652, accuracy : 0.769900
+
+After the training of some steps (depends on the setting) or the job is
+finished, SINGA will [checkpoint](checkpoint.html) the model parameters.
+
+## Details
+
+To train a model in SINGA, you need to prepare the datasets,
+and a job configuration which specifies the neural net structure, training
+algorithm (BP or CD), SGD update algorithm (e.g. Adagrad),
+number of training/test steps, etc.
+
+### Data preparation
+
+Before using SINGA, you need to write a program to pre-process the dataset you
+use to a format that SINGA can read. Please refer to the
+[Data Preparation](data.html) to get details about preparing
+this MNIST dataset.
+
+
+### Neural net
+
+<div style = "text-align: center">
+<img src = "../images/example-mlp.png" style = "width: 230px">
+<br/><strong>Figure 1 - Net structure of the MLP example. </strong></img>
+</div>
+
+
+Figure 1 shows the structure of the simple MLP model, which is constructed following
+[Ciresan's paper](http://arxiv.org/abs/1003.0358). The dashed circle contains
+two layers which represent one feature transformation stage. There are 6 such
+stages in total. They sizes of the [InnerProductLayer](layer.html#innerproductlayer)s in these circles decrease from
+2500->2000->1500->1000->500->10.
+
+Next we follow the guide in [neural net page](neural-net.html)
+and [layer page](layer.html) to write the neural net configuration.
+
+* We configure an input layer to read the training/testing records from a disk file.
+
+ layer {
+ name: "data"
+ type: kRecordInput
+ store_conf {
+ backend: "kvfile"
+ path: "examples/mnist/train_data.bin"
+ random_skip: 5000
+ batchsize: 64
+ shape: 784
+ std_value: 127.5
+ mean_value: 127.5
+ }
+ exclude: kTest
+ }
+
+ layer {
+ name: "data"
+ type: kRecordInput
+ store_conf {
+ backend: "kvfile"
+ path: "examples/mnist/test_data.bin"
+ batchsize: 100
+ shape: 784
+ std_value: 127.5
+ mean_value: 127.5
+ }
+ exclude: kTrain
+ }
+
+
+* All [InnerProductLayer](layer.html#innerproductlayer)s are configured similarly as,
+
+ layer{
+ name: "fc1"
+ type: kInnerProduct
+ srclayers:"data"
+ innerproduct_conf{
+ num_output: 2500
+ }
+ param{
+ name: "w1"
+ ...
+ }
+ param{
+ name: "b1"
+ ..
+ }
+ }
+
+ with the `num_output` decreasing from 2500 to 10.
+
+* A [STanhLayer](layer.html#stanhlayer) is connected to every InnerProductLayer
+except the last one. It transforms the feature via scaled tanh function.
+
+ layer{
+ name: "tanh1"
+ type: kSTanh
+ srclayers:"fc1"
+ }
+
+* The final [Softmax loss layer](layer.html#softmaxloss) connects
+to LabelLayer and the last STanhLayer.
+
+ layer{
+ name: "loss"
+ type:kSoftmaxLoss
+ softmaxloss_conf{ topk:1 }
+ srclayers:"fc6"
+ srclayers:"data"
+ }
+
+### Updater
+
+The [normal SGD updater](updater.html#updater) is selected.
+The learning rate shrinks by 0.997 every 60 steps (i.e., one epoch).
+
+ updater{
+ type: kSGD
+ learning_rate{
+ base_lr: 0.001
+ type : kStep
+ step_conf{
+ change_freq: 60
+ gamma: 0.997
+ }
+ }
+ }
+
+### TrainOneBatch algorithm
+
+The MLP model is a feed-forward model, hence
+[Back-propagation algorithm](train-one-batch#back-propagation)
+is selected.
+
+ train_one_batch {
+ alg: kBP
+ }
+
+### Cluster setting
+
+The following configuration set a single worker and server for training.
+[Training frameworks](frameworks.html) page introduces configurations of a couple of distributed
+training frameworks.
+
+ cluster {
+ nworker_groups: 1
+ nserver_groups: 1
+ }