| |
| |
| |
| <!DOCTYPE html> |
| <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]--> |
| <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]--> |
| <head> |
| <meta charset="utf-8"> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| |
| <title>Programming Guide — incubator-singa 0.3.0 documentation</title> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" /> |
| |
| |
| |
| |
| |
| <link rel="top" title="incubator-singa 0.3.0 documentation" href="../index.html"/> |
| |
| |
| <script src="../_static/js/modernizr.min.js"></script> |
| |
| </head> |
| |
| <body class="wy-body-for-nav" role="document"> |
| |
| <div class="wy-grid-for-nav"> |
| |
| |
| <nav data-toggle="wy-nav-shift" class="wy-nav-side"> |
| <div class="wy-side-scroll"> |
| <div class="wy-side-nav-search"> |
| |
| |
| |
| <a href="../index.html" class="icon icon-home"> incubator-singa |
| |
| |
| |
| |
| <img src="../_static/singa.png" class="logo" /> |
| |
| </a> |
| |
| |
| |
| |
| <div class="version"> |
| 0.3.0 |
| </div> |
| |
| |
| |
| |
| <div role="search"> |
| <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> |
| <input type="text" name="q" placeholder="Search docs" /> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </div> |
| |
| |
| </div> |
| |
| <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> |
| |
| |
| |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../downloads.html">Download SINGA</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="index.html">Documentation</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">Development</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../develop/schedule.html">Development Schedule</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../develop/how-contribute.html">How to Contribute to SINGA</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../develop/contribute-code.html">How to Contribute Code</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../develop/contribute-docs.html">How to Contribute Documentation</a></li> |
| </ul> |
| <p class="caption"><span class="caption-text">Community</span></p> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../community/source-repository.html">Source Repository</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../community/mail-lists.html">Project Mailing Lists</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../community/issue-tracking.html">Issue Tracking</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../community/team-list.html">The SINGA Team</a></li> |
| </ul> |
| |
| |
| |
| </div> |
| </div> |
| </nav> |
| |
| <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> |
| |
| |
| <nav class="wy-nav-top" role="navigation" aria-label="top navigation"> |
| <i data-toggle="wy-nav-top" class="fa fa-bars"></i> |
| <a href="../index.html">incubator-singa</a> |
| </nav> |
| |
| |
| |
| <div class="wy-nav-content"> |
| <div class="rst-content"> |
| |
| |
| |
| |
| |
| |
| <div role="navigation" aria-label="breadcrumbs navigation"> |
| <ul class="wy-breadcrumbs"> |
| <li><a href="../index.html">Docs</a> »</li> |
| |
| <li>Programming Guide</li> |
| <li class="wy-breadcrumbs-aside"> |
| |
| |
| |
| </li> |
| </ul> |
| <hr/> |
| </div> |
| <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> |
| <div itemprop="articleBody"> |
| |
| <div class="section" id="programming-guide"> |
| <span id="programming-guide"></span><h1>Programming Guide<a class="headerlink" href="#programming-guide" title="Permalink to this headline">¶</a></h1> |
| <hr class="docutils" /> |
| <p>To submit a training job, users must provide the configuration of the |
| four components shown in Figure 1:</p> |
| <ul class="simple"> |
| <li>a <a class="reference external" href="neural-net.html">NeuralNet</a> describing the neural net structure with the detailed layer setting and their connections;</li> |
| <li>a <a class="reference external" href="train-one-batch.html">TrainOneBatch</a> algorithm which is tailored for different model categories;</li> |
| <li>an <a class="reference external" href="updater.html">Updater</a> defining the protocol for updating parameters at the server side;</li> |
| <li>a <a class="reference external" href="distributed-training.html">Cluster Topology</a> specifying the distributed architecture of workers and servers.</li> |
| </ul> |
| <p>The <em>Basic user guide</em> section describes how to submit a training job using |
| built-in components; while the <em>Advanced user guide</em> section presents details |
| on writing user’s own main function to register components implemented by |
| themselves. In addition, the training data must be prepared, which has the same |
| <a class="reference external" href="data.html">process</a> for both advanced users and basic users.</p> |
| <p><img src="../_static/images/overview.png" align="center" width="400px"/></p> |
| <p><span><strong>Figure 1 - SINGA overview.</strong></span></p> |
| <div class="section" id="basic-user-guide"> |
| <span id="basic-user-guide"></span><h2>Basic user guide<a class="headerlink" href="#basic-user-guide" title="Permalink to this headline">¶</a></h2> |
| <p>Users can use the default main function provided SINGA to submit the training |
| job. For this case, a job configuration file written as a google protocol |
| buffer message for the <a class="reference external" href="../api/classsinga_1_1JobProto.html">JobProto</a> must be provided in the command line,</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">./</span><span class="nb">bin</span><span class="o">/</span><span class="n">singa</span><span class="o">-</span><span class="n">run</span><span class="o">.</span><span class="n">sh</span> <span class="o">-</span><span class="n">conf</span> <span class="o"><</span><span class="n">path</span> <span class="n">to</span> <span class="n">job</span> <span class="n">conf</span><span class="o">></span> <span class="p">[</span><span class="o">-</span><span class="n">resume</span><span class="p">]</span> |
| </pre></div> |
| </div> |
| <p><code class="docutils literal"><span class="pre">-resume</span></code> is for continuing the training from last |
| <a class="reference external" href="checkpoint.html">checkpoint</a>. |
| The <a class="reference external" href="mlp.html">MLP</a> and <a class="reference external" href="cnn.html">CNN</a> |
| examples use built-in components. Please read the corresponding pages for their |
| job configuration files. The subsequent pages will illustrate the details on |
| each component of the configuration.</p> |
| </div> |
| <div class="section" id="advanced-user-guide"> |
| <span id="advanced-user-guide"></span><h2>Advanced user guide<a class="headerlink" href="#advanced-user-guide" title="Permalink to this headline">¶</a></h2> |
| <p>If a user’s model contains some user-defined components, e.g., |
| <a class="reference external" href="updater.html">Updater</a>, he has to write a main function to |
| register these components. It is similar to Hadoop’s main function. Generally, |
| the main function should</p> |
| <ul class="simple"> |
| <li>initialize SINGA, e.g., setup logging.</li> |
| <li>register user-defined components.</li> |
| <li>create and pass the job configuration to SINGA driver</li> |
| </ul> |
| <p>An example main function is like</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1">#include "singa.h"</span> |
| <span class="c1">#include "user.h" // header for user code</span> |
| |
| <span class="nb">int</span> <span class="n">main</span><span class="p">(</span><span class="nb">int</span> <span class="n">argc</span><span class="p">,</span> <span class="n">char</span><span class="o">**</span> <span class="n">argv</span><span class="p">)</span> <span class="p">{</span> |
| <span class="n">singa</span><span class="p">::</span><span class="n">Driver</span> <span class="n">driver</span><span class="p">;</span> |
| <span class="n">driver</span><span class="o">.</span><span class="n">Init</span><span class="p">(</span><span class="n">argc</span><span class="p">,</span> <span class="n">argv</span><span class="p">);</span> |
| <span class="nb">bool</span> <span class="n">resume</span><span class="p">;</span> |
| <span class="o">//</span> <span class="n">parse</span> <span class="n">resume</span> <span class="n">option</span> <span class="kn">from</span> <span class="nn">argv.</span> |
| |
| <span class="o">//</span> <span class="n">register</span> <span class="n">user</span> <span class="n">defined</span> <span class="n">layers</span> |
| <span class="n">driver</span><span class="o">.</span><span class="n">RegisterLayer</span><span class="o"><</span><span class="n">FooLayer</span><span class="o">></span><span class="p">(</span><span class="n">kFooLayer</span><span class="p">);</span> |
| <span class="o">//</span> <span class="n">register</span> <span class="n">user</span> <span class="n">defined</span> <span class="n">updater</span> |
| <span class="n">driver</span><span class="o">.</span><span class="n">RegisterUpdater</span><span class="o"><</span><span class="n">FooUpdater</span><span class="o">></span><span class="p">(</span><span class="n">kFooUpdater</span><span class="p">);</span> |
| <span class="o">...</span> |
| <span class="n">auto</span> <span class="n">jobConf</span> <span class="o">=</span> <span class="n">driver</span><span class="o">.</span><span class="n">job_conf</span><span class="p">();</span> |
| <span class="o">//</span> <span class="n">update</span> <span class="n">jobConf</span> |
| |
| <span class="n">driver</span><span class="o">.</span><span class="n">Train</span><span class="p">(</span><span class="n">resume</span><span class="p">,</span> <span class="n">jobConf</span><span class="p">);</span> |
| <span class="k">return</span> <span class="mi">0</span><span class="p">;</span> |
| <span class="p">}</span> |
| </pre></div> |
| </div> |
| <p>The Driver class’ <code class="docutils literal"><span class="pre">Init</span></code> method will load a job configuration file provided by |
| users as a command line argument (<code class="docutils literal"><span class="pre">-conf</span> <span class="pre"><job</span> <span class="pre">conf></span></code>). It contains at least the |
| cluster topology and returns the <code class="docutils literal"><span class="pre">jobConf</span></code> for users to update or fill in |
| configurations of neural net, updater, etc. If users define subclasses of |
| Layer, Updater, Worker and Param, they should register them through the driver. |
| Finally, the job configuration is submitted to the driver which starts the |
| training.</p> |
| <p>We will provide helper functions to make the configuration easier in the |
| future, like <a class="reference external" href="https://github.com/fchollet/keras">keras</a>.</p> |
| <p>Users need to compile and link their code (e.g., layer implementations and the main |
| file) with SINGA library (<em>.libs/libsinga.so</em>) to generate an |
| executable file, e.g., with name <em>mysinga</em>. To launch the program, users just pass the |
| path of the <em>mysinga</em> and base job configuration to <em>./bin/singa-run.sh</em>.</p> |
| <div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">./</span><span class="nb">bin</span><span class="o">/</span><span class="n">singa</span><span class="o">-</span><span class="n">run</span><span class="o">.</span><span class="n">sh</span> <span class="o">-</span><span class="n">conf</span> <span class="o"><</span><span class="n">path</span> <span class="n">to</span> <span class="n">job</span> <span class="n">conf</span><span class="o">></span> <span class="o">-</span><span class="n">exec</span> <span class="o"><</span><span class="n">path</span> <span class="n">to</span> <span class="n">mysinga</span><span class="o">></span> <span class="p">[</span><span class="n">other</span> <span class="n">arguments</span><span class="p">]</span> |
| </pre></div> |
| </div> |
| <p>The <a class="reference external" href="rnn.html">RNN application</a> provides a full example of |
| implementing the main function for training a specific RNN model.</p> |
| </div> |
| </div> |
| |
| |
| </div> |
| </div> |
| <footer> |
| |
| |
| <hr/> |
| |
| <div role="contentinfo"> |
| <p> |
| © Copyright 2016 The Apache Software Foundation. All rights reserved. Apache Singa, Apache, the Apache feather logo, and the Apache Singa project logos are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.. |
| |
| </p> |
| </div> |
| Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. |
| |
| </footer> |
| |
| </div> |
| </div> |
| |
| </section> |
| |
| </div> |
| |
| |
| |
| |
| |
| <script type="text/javascript"> |
| var DOCUMENTATION_OPTIONS = { |
| URL_ROOT:'../', |
| VERSION:'0.3.0', |
| COLLAPSE_INDEX:false, |
| FILE_SUFFIX:'.html', |
| HAS_SOURCE: true |
| }; |
| </script> |
| <script type="text/javascript" src="../_static/jquery.js"></script> |
| <script type="text/javascript" src="../_static/underscore.js"></script> |
| <script type="text/javascript" src="../_static/doctools.js"></script> |
| |
| |
| |
| |
| |
| <script type="text/javascript" src="../_static/js/theme.js"></script> |
| |
| |
| |
| |
| <script type="text/javascript"> |
| jQuery(function () { |
| SphinxRtdTheme.StickyNav.enable(); |
| }); |
| </script> |
| |
| |
| |
| <div class="rst-versions shift-up" data-toggle="rst-versions" role="note" aria-label="versions"> |
| <img src="../_static/apache.jpg"> |
| |
| <span class="rst-current-version" data-toggle="rst-current-version"> |
| <span class="fa fa-book"> incubator-singa </span> |
| v: 0.3.0 |
| <span class="fa fa-caret-down"></span> |
| </span> |
| <div class="rst-other-versions"> |
| <dl> |
| <dt>Languages</dt> |
| <dd><a href="../../en/index.html">English</a></dd> |
| <dd><a href="../../zh/index.html">中文</a></dd> |
| <dd><a href="../../jp/index.html">日本語</a></dd> |
| <dd><a href="../../kr/index.html">한국어</a></dd> |
| </dl> |
| </div> |
| </div> |
| |
| <a href="https://github.com/apache/incubator-singa"> |
| <img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;" |
| src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" |
| alt="Fork me on GitHub"> |
| </a> |
| |
| |
| |
| |
| </body> |
| </html> |
