gettingstarted.html



<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Rickshaw Tutorial &#8212; rickshaw 1.5.3 documentation</title>
    <link rel="stylesheet" href="_static/numpy_friendly.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Noticia+Text|Open+Sans|Droid+Sans+Mono" type="text/css" />
    <script type="text/javascript" src="_static/documentation_options.js"></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/jquery.cookie.js"></script>
    <script type="text/javascript" src="_static/cloud.base.js"></script>
    <script type="text/javascript" src="_static/cloud.js"></script>
    <link rel="shortcut icon" href="_static/rickshaw_128px.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="prev" title="Lazy and Self-destructive Tools (rickshaw.lazyasd)" href="api/lazyasd.html" />
     
        <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="canonical" href="http://www.ergs.sc.edu/rickshaw-docs/gettingstarted.html"/>

  </head><body>
    <div class="relbar-top">
        
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> &nbsp; &nbsp;</li>
        <li class="right" >
          <a href="api/lazyasd.html" title="Lazy and Self-destructive Tools (rickshaw.lazyasd)"
             accesskey="P">previous</a> &nbsp; &nbsp;</li>
    <li><a href="index.html">rickshaw 1.5.3 documentation</a> &#187;</li>
 
      </ul>
    </div>
    </div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="rickshaw-tutorial">
<h1>Rickshaw Tutorial<a class="headerlink" href="#rickshaw-tutorial" title="Permalink to this headline">¶</a></h1>
<p>You can get started using Rickshaw by following these steps:</p>
<ol class="arabic simple">
<li>Clone the Git repo</li>
<li>Run the installation script</li>
<li>Write a specification file (optional)</li>
</ol>
<div class="section" id="rickshaw-dependencies">
<h2>Rickshaw Dependencies<a class="headerlink" href="#rickshaw-dependencies" title="Permalink to this headline">¶</a></h2>
<p>First, make sure you have the following dependencies installed for Rickshaw to work correctly.</p>
<ul class="simple">
<li>Cyclus</li>
<li>Cycamore</li>
<li>websockets</li>
<li>DockerPy</li>
<li>sphinx*</li>
<li>cloud_sptheme*</li>
<li>numpydoc*</li>
</ul>
<p>* <em>for building documentation</em></p>
</div>
<div class="section" id="cloning-the-repo">
<h2>1. Cloning the Repo<a class="headerlink" href="#cloning-the-repo" title="Permalink to this headline">¶</a></h2>
<p>Run the following from the command line:</p>
<p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">https://github.com/ergs/rickshaw.git</span></code></p>
</div>
<div class="section" id="installing-rickshaw">
<h2>2. Installing Rickshaw<a class="headerlink" href="#installing-rickshaw" title="Permalink to this headline">¶</a></h2>
<p>From the top-level <code class="docutils literal notranslate"><span class="pre">rickshaw</span></code> directory, run <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></code></p>
</div>
<div class="section" id="writing-a-specification-file-optional">
<h2>3. Writing a Specification File (optional)<a class="headerlink" href="#writing-a-specification-file-optional" title="Permalink to this headline">¶</a></h2>
<p>Specification files are Rickshaw input files in which you can define constraints
for generation. For instance, you have the ability to restrict Rickshaw to a subset
of Archetypes, Niches, Recipes, etc.</p>
<p>A specification file can be in either JSON or Python format.</p>
<p>Here’s an example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># test_specification_input.py</span>
<span class="p">{</span>
    <span class="c1"># Simulation data definitions</span>
    <span class="s1">&#39;simulation&#39;</span><span class="p">:</span> <span class="p">{</span><span class="s1">&#39;recipe&#39;</span><span class="p">:</span> <span class="p">[{</span><span class="s1">&#39;basis&#39;</span><span class="p">:</span> <span class="s1">&#39;mass&#39;</span><span class="p">,</span>
                               <span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="s1">&#39;commod_recipe&#39;</span><span class="p">,</span>
                               <span class="s1">&#39;nuclide&#39;</span><span class="p">:</span> <span class="p">[{</span><span class="s1">&#39;comp&#39;</span><span class="p">:</span> <span class="p">[</span><span class="mf">0.5</span><span class="p">,</span> <span class="mf">1.0</span><span class="p">],</span> <span class="s1">&#39;id&#39;</span><span class="p">:</span> <span class="nb">int</span><span class="p">(</span><span class="s1">&#39;010010000&#39;</span><span class="p">)},</span>
                                           <span class="p">{</span><span class="s1">&#39;comp&#39;</span><span class="p">:</span> <span class="bp">None</span><span class="p">,</span> <span class="s1">&#39;id&#39;</span><span class="p">:</span> <span class="nb">int</span><span class="p">(</span><span class="s1">&#39;010010000&#39;</span><span class="p">)}]</span>
                             <span class="p">}]</span>
                  <span class="p">},</span>
    <span class="c1"># Desired niches for Rickshaw to use</span>
    <span class="s1">&#39;niche_links&#39;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;mine&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;reactor:hwr&quot;</span><span class="p">,</span> <span class="s2">&quot;reactor:lwr&quot;</span><span class="p">},</span>
                    <span class="s2">&quot;reactor:hwr&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;repository&quot;</span><span class="p">}</span> <span class="p">,</span>
                    <span class="s2">&quot;reactor:lwr&quot;</span><span class="p">:{</span><span class="s2">&quot;repository&quot;</span><span class="p">},</span>
                    <span class="s2">&quot;repository&quot;</span><span class="p">:</span> <span class="p">{</span><span class="bp">None</span><span class="p">}</span>
                   <span class="p">},</span>
    <span class="c1"># Disired archetypes which fit desired niches</span>
    <span class="s1">&#39;archetypes&#39;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;mine&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;:cycamore:Source&quot;</span><span class="p">},</span>
                   <span class="s2">&quot;reactor:hwr&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;:cycamore:Reactor&quot;</span><span class="p">},</span>
                   <span class="s2">&quot;reactor:lwr&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;:cycamore:Reactor&quot;</span><span class="p">},</span>
                   <span class="s2">&quot;repository&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;:cycamore:Sink&quot;</span><span class="p">}</span>
                  <span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Any of the following may be specified as top-level keys in your file:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">niche_links</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">archetypes</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">commodities</span></code></li>
</ul>
<p>The above define the allowed structure of a Rickshaw-generated input file.</p>
<p>You’ll also notice the top-level <code class="docutils literal notranslate"><span class="pre">simulation</span></code> key in the specification file.
This is where you can define literal data or data ranges for generated simulations.
At this time, only the <code class="docutils literal notranslate"><span class="pre">recipe</span></code> block placed here is read by Rickshaw.</p>
</div>
<div class="section" id="running-rickshaw">
<h2>Running Rickshaw<a class="headerlink" href="#running-rickshaw" title="Permalink to this headline">¶</a></h2>
<p>After following the steps above, you can run Rickshaw via the <code class="docutils literal notranslate"><span class="pre">rickshaw</span></code> command from the command line.
With no flags or options set, Rickshaw will produce one output file with no constraining specification.</p>
<ul>
<li><p class="first">To specify the number of input files to generate, use <code class="docutils literal notranslate"><span class="pre">rickshaw</span> <span class="pre">-n</span> <span class="pre">[number</span> <span class="pre">of</span> <span class="pre">runs]</span></code>.
Each file will be saved in the format <code class="docutils literal notranslate"><span class="pre">x.json</span></code> where <code class="docutils literal notranslate"><span class="pre">x</span></code> is in the range [0, n-1].</p>
</li>
<li><p class="first">To load a specification file, use <code class="docutils literal notranslate"><span class="pre">rickshaw</span> <span class="pre">-i</span> <span class="pre">[file_name]</span></code></p>
</li>
<li><p class="first">To run Rickshaw in verbose mode, use <code class="docutils literal notranslate"><span class="pre">rickshaw</span> <span class="pre">-v</span></code>.
This will pretty print every generated input file.</p>
</li>
<li><p class="first">To run Rickshaw in generate-and-run mode, you can use either:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">rickshaw</span> <span class="pre">-rh</span></code> (for HDF5 output)</li>
<li><code class="docutils literal notranslate"><span class="pre">rickshaw</span> <span class="pre">-rs</span></code> (for SQLite output)</li>
<li><strong>or both</strong></li>
</ul>
<p>All generated input files will immediately be run by Cyclus to the output file format(s) specified.</p>
</li>
</ul>
</div>
<div class="section" id="cool-note">
<h2>Cool note!<a class="headerlink" href="#cool-note" title="Permalink to this headline">¶</a></h2>
<p>The above options can be mixed to achieve your desired behavior, a la:</p>
<p><code class="docutils literal notranslate"><span class="pre">rickshaw</span> <span class="pre">-n</span> <span class="pre">10</span> <span class="pre">-i</span> <span class="pre">test.py</span> <span class="pre">-v</span> <span class="pre">-rh</span> <span class="pre">-rs</span></code></p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
        <p class="logo"><a href="index.html" title="index">
          <img class="logo" src="_static/rickshaw.svg" alt="Logo"/>
        </a></p><div class="sphinx-toc sphinxlocaltoc">
    <h3><a href="index.html">Page contents</a></h3>
    <ul>
<li><a class="reference internal" href="#">Rickshaw Tutorial</a><ul>
<li><a class="reference internal" href="#rickshaw-dependencies">Rickshaw Dependencies</a></li>
<li><a class="reference internal" href="#cloning-the-repo">1. Cloning the Repo</a></li>
<li><a class="reference internal" href="#installing-rickshaw">2. Installing Rickshaw</a></li>
<li><a class="reference internal" href="#writing-a-specification-file-optional">3. Writing a Specification File (optional)</a></li>
<li><a class="reference internal" href="#running-rickshaw">Running Rickshaw</a></li>
<li><a class="reference internal" href="#cool-note">Cool note!</a></li>
</ul>
</li>
</ul>

  </div>
  <div class="sphinxprev">
    <h4>Previous page</h4>
    <p class="topless"><a href="api/lazyasd.html"
                          title="Previous page">&larr; Lazy and Self-destructive Tools (<code class="docutils literal notranslate"><span class="pre">rickshaw.lazyasd</span></code>)</a></p>
  </div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/gettingstarted.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
    
    
        <div class="sidebar-toggle-group no-js">
            
            <button class="sidebar-toggle" id="sidebar-hide" title="Hide the sidebar menu">
                 «
                <span class="show-for-small">hide menu</span>
                
            </button>
            <button class="sidebar-toggle" id="sidebar-show" title="Show the sidebar menu">
                
                <span class="show-for-small">menu</span>
                <span class="hide-for-small">sidebar</span>
                 »
            </button>
        </div>
    
      <div class="clearer"></div>
    </div>
    <div class="relbar-bottom">
        
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> &nbsp; &nbsp;</li>
        <li class="right" >
          <a href="api/lazyasd.html" title="Lazy and Self-destructive Tools (rickshaw.lazyasd)"
             >previous</a> &nbsp; &nbsp;</li>
    <li><a href="index.html">rickshaw 1.5.3 documentation</a> &#187;</li>
 
      </ul>
    </div>
    </div>

    <div class="footer" role="contentinfo">
        &#169; Copyright 2016-2017, ERGS (Anthony Scopatz et al.).
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.1.
    </div>
    <!-- cloud_sptheme 1.4 -->
  </body>
</html>