Merge pull request #293 from arfc/tutorial

Tutorial

source/arche/resources.rst

@@ -55,7 +55,7 @@ terms of the ``cyclus::Resource`` superclass.  So it will sometimes be
 necessary to cast down to the appropriate resource subclass.  |Cyclus| provides
 an overloaded ResCast function for casting convenience:
 
-**C++*:*
+**C++:**
 
 .. code-block:: c++
 

source/arche/timestep.rst

@@ -134,7 +134,7 @@ Future decommissions can be scheduled by any :term:`agent` using the
 ``cyclus::Context``'s ``SchedDecom`` member function. A decommission can be
 scheduled for the current time step or any future time step.
 
-Decommissioning occurrs at the end of a time step. Therefore, an agent with a lifetime
+Decommissioning occurs at the end of a time step. Therefore, an agent with a lifetime
 of 1 would be decommissioned on the same time step it was built. The lifetime of an
 agent can be back calculated by `1+exit_time-start_time`.
 
@@ -143,4 +143,3 @@ Further Reading
 
 For a more in depth (and historical) discussion, see `CEP 20
 <http://fuelcycle.org/cep/cep20.html>`_.
-

source/arche/toolkit.rst

@@ -166,8 +166,8 @@ composable, agent-managed state variables:
 * ``cyclus::toolkit::SupplyDemandManager``: an interface for querying the supply
   and demand on commodities
 
-  Geographic Informasion System (GIS) Class [C++]
-  +++++++++++++++++++++++++++++++++++++++++++++++
+Geographic Informasion System (GIS) Class [C++]
++++++++++++++++++++++++++++++++++++++++++++++++
   The ``cyclus::toolkit::GIS`` class provide an option to add geographic coordinates
   of its friend classes. Haversine distance calculations between two facilities or
-  agents with GIS coordinates can be performed as well.
+  agents with GIS coordinates can be performed as well.

source/cep/cep-0018-1.bib

@@ -85,13 +85,15 @@ @article{nagurney_supply_2002
 journal = {Transportation Research Part E: Logistics and Transportation Review},
 volume = {38},
 number = {5},
-pages = {281 ^`^s303},
+
+pages = {281 - 303},
 year = {2002},
+note = {},
 issn = {1366-5545},
 doi = {10.1016/S1366-5545(01)00020-5},
 url = {http://www.sciencedirect.com/science/article/pii/S1366554501000205},
 author = {Nagurney, Anna and Dong, June and Zhang, Ding},
-keywords = {Supply chains;Networks;Equilibrium;Variational inequalities;Decentralized decision-making}
+keywords = {Supply chains;Networks;Equilibrium;Variational inequalities;Decentralized decision-making},
 }
 
 @ARTICLE{song_nash_2002, 

source/conf.py

@@ -33,7 +33,8 @@
     warnings.warn('WARNING: Continuing without cypp.py!!!', RuntimeWarning)
 
 if len(h) != 0:
-    fname = [x[10:].strip() for x in h.splitlines() if x.startswith('filename:')][0]
+    fname = [x[10:].strip()
+             for x in h.splitlines() if x.startswith('filename:')][0]
     sys.path.insert(1, os.path.dirname(fname))
 
 
@@ -67,7 +68,7 @@
 # General information about the project.
 project = u'Cyclus'
 copyright = (u'2012-2016, University of Wisconsin Computational Nuclear '
-              'Engineering Research Group')
+             'Engineering Research Group')
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -145,7 +146,7 @@
     'externalrefs': False,
     'stickysidebar': False,
     'highlighttoc': False,
-    }
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = ['_theme', csp.get_theme_dir()]
@@ -220,21 +221,21 @@
 # -- Options for LaTeX output --------------------------------------------------
 
 latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+    # The paper size ('letterpaper' or 'a4paper').
+    # 'papersize': 'letterpaper',
 
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
+    # The font size ('10pt', '11pt' or '12pt').
+    # 'pointsize': '10pt',
 
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
+    # Additional stuff for the LaTeX preamble.
+    # 'preamble': '',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'Cyclus.tex', u'Cyclus Documentation',
-   u'Cyclus Developer', 'manual'),
+    ('index', 'Cyclus.tex', u'Cyclus Documentation',
+     u'Cyclus Developer', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -277,9 +278,9 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'Cyclus', u'Cyclus Documentation',
-   u'Cyclus Developers', 'Cyclus', 'One line description of project.',
-   'Miscellaneous'),
+    ('index', 'Cyclus', u'Cyclus Documentation',
+     u'Cyclus Developers', 'Cyclus', 'One line description of project.',
+     'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.

source/user/tutorial/add_arche.rst

@@ -1,32 +1,32 @@
-Understanding and Adding Archetypes to Your Scenario
-++++++++++++++++++++++++++++++++++++++++++++++++++++
+Understanding Archetypes 
+++++++++++++++++++++++++
 
 Concept: Archetypes
-=========================================
+===================
 
 One of the principal features of |Cyclus| is the ability for users to easily
 switch between different models of fuel cycle facilities.  Models may differ
 in the way they choose to represent the physics of the facility, or in the way
 they choose for the facility to interact with other facilities, or both. In
 |Cyclus|, we call each of these different models an :term:`archetype`.
 
-Archetype Example: Reactor Fidelity
-------------------------------------
+Archetype Example
+-----------------
 
 The easiest way for most fuel cycle analysts to understand the difference
-between archetypes is through the example of a reactor model.  
+between archetypes is through the example of a reactor model.
 
 * The simplest possible reactor archetype uses the concept of fixed input and
   output recipes to define the transmutation of material.  Such a reactor
   might assume that all material that it receives matches its desired input
   recipe, and that all the material that it then ships as used fuel will match
   its prescribed output recipe.  This will probably run the fastest.
 * A more sophisticated reactor archetype uses some form of tabulated data to
-  determine both performance characteristics and used fuel discharge
-  composition.  It could be as simple as interpolating between a set of
+  determine both **performance characteristics** and **used fuel discharge
+  composition**.  It could be as simple as interpolating between a set of
   possible input recipes and then using that interpolation on a set of
   corresponding output recipes.  A more complex version of such an archetype
-  could even have tabulated reactor physics paramters for more fidelity.
+  could even have tabulated reactor physics parameters for more fidelity.
 * The most sophisticated reactor archetype may actually be a wrapper for fuel
   depletion software, and perform a full depletion calculation each time new
   fuel arrives at the reactor.  This will probably take the most computer time
@@ -45,56 +45,167 @@ simple models and are useful for tutorials such as this, and as a standard way
 to model facilities that may be at the peripheral of a problem.  The Cycamore
 facility archetypes are:
 
-* **Source:** This generic source of material may fill the role of any
+* **Source:** `Source <http://fuelcycle.org/user/cycamoreagents.html#cycamore-source>`_ 
+  is a generic source of material may fill the role of any
   facility that produces fresh material.  Depending on how much of the fuel
-  cycle a user wants to model explicity, this could fill the role of a uranium
-  mine, an enrichment facility, a fuel fabrication facility, etc.
-* **Enrichment:** This facility archetype implements the standard equations for
+  cycle a user wants to model explicitly, this could fill the role of a uranium
+  mine, an enrichment facility, a fuel fabrication facility, import of a commodity from 
+  outside simulated facilities, etc. The Source facility produces resources at a user-specified 
+  rate and may be limited to a user-specified total inventory.
+* **Enrichment:** `Enrichment <http://fuelcycle.org/user/cycamoreagents.html#cycamore-enrichment>`_ 
+  is a facility archetype that implements the standard equations for
   enrichment of U-235 in U-238, with a constrained total enrichment capacity.
-* **Reactor:** This facility archetype uses simple fuel recipes for a reactor
-  that reloads batches of assemblies at regular intervals.
-* **Separations:** This facility archetype takes a number of input streams and
+* **Reactor:** `Reactor <http://fuelcycle.org/user/cycamoreagents.html#cycamore-reactor>`_ 
+  is a facility archetype which uses fresh and spent fuel recipes to model fuel transmutation.
+  Fuel is modeled as batches and assemblies that are reloaded at regular intervals.
+* **Separations:** `Separations <http://fuelcycle.org/user/cycamoreagents.html#cycamore-separations>`_ 
+  is a facility archetype that receives one or more material streams and
   separates all the isotopes into a number of output streams.
-* **FuelFab:** This facility archetype mixes streams of fissile and
+* **FuelFab:** `FuelFab <http://fuelcycle.org/user/cycamoreagents.html#cycamore-fuelfab>`_ is 
+  a facility archetype that mixes streams of fissile and
   fissionable material in order to best approximate a given recipe using the
   d-factor approach.
-* **Sink:** This generic sink of material may fill the role of any facility
+* **Sink:** `Sink <http://fuelcycle.org/user/cycamoreagents.html#cycamore-sink>`_ is a generic 
+  sink of material that may fill the role of any facility
   that permanently holds used nuclear material.  Depending on how much of the
   fuel cycle a user wants to model explicitly, this could fill the role of a
-  geologic repository, an interim storage facility, etc.
+  geologic repository, an interim storage facility, export of a commodity to outside simulated facilities, etc.
 
 
 Activity: Discover the Available Archetypes
----------------------------------------------
-
-Since archetypes can change without having to resinstall |Cyclus|, there is
-the ability to automatically discover which archetypes are available.
-
-1. Press the "Discover Archetypes" button to update the archetypes available to you.
-
-.. image:: disc_arche.png
-    :align: center
-    :alt: View of archetype discovery pane.
+===========================================
+If using |Cyclus| on your machine, the archetypes available to you are only those that you have downloaded. 
+To check which archetypes are downloaded on your machine run the command ``cyclus -a`` from your terminal.
 
-2. Select the "Add Archetype to Simulation" drop-down box to see which
-   archetypes are available.
+If you are not running |Cyclus| on your machine, the archetypes available to you include those in Cycamore, which 
+can be found on the `archetypes
+<http://fuelcycle.org/user/cycamoreagents.html>`_ webpage.
 
-Activity: Select Archetypes to Use in this Scneario
-------------------------------------------------------
 
-After discovering which archetypes are available on your system, you are able to select which
-subset of archetypes will be used in this particular scenario.
+What archetypes can you see yourself using in your research?
 
-1. For this scenario, select each of these archetypes from the drop down box.
-
-* *cycamore Source*: to act as the mine
-* *cycamore Enrichment*: to act as the enrichment facility
-* *cycamore Reactor*: to act as the LWR 
-* *cycamore Sink*: to act as the geoligic respository
-
-Notice how these now appear in the window on the right.
-
-.. image:: arche_ribbon.png
-    :align: center
-    :width: 100%
-    :alt: View of archetype ribbon after adding archetypes
+Concept: Third-Party Archetypes
+=========================================
+`Third-Party <http://fuelcycle.org/user/index.html#=third-party>`_ Archetypes 
+complement the initial archetypes available in Cycamore and are not necessarily 
+maintained by the |Cyclus| core development team.  Popular Third-Party Archetypes are:
+
+* Bright-lite
+* Cyborg
+* Mbmore Archetypes
+* rwc Archetypes
+
+Review the `archetype developer tutorial <http://fuelcycle.org/arche/tutorial/input_files.html>`_
+for more information on making your own Archetypes.
+
+Activity: Adding archetypes
+===========================
+
+After discovering which archetypes are available, we will select which
+subset of archetypes to use in this particular scenario.
+
+The archetypes we will use in our simulation include:
+
+-  ``cycamore Source``: to act as the mine
+-  ``cycamore Enrichment``:to act as the enrichment facility
+-  ``cycamore Reactor``: to act as the LWR
+-  ``cycamore Sink``: to act as the geological repository. 
+
+A user identifies the simulation ``archetypes`` in the archetype block of the |Cyclus| input file. 
+The ``archetype`` block is located after the simulation control block and takes the form:
+
+.. code-block:: XML
+
+    <archetypes>
+        <spec>
+          <lib>lib1</lib>
+          <name>arch_1</name>
+        </spec>
+        <spec>
+          <lib>lib2</lib>
+          <name>arch_2</name>
+        </spec>
+    </archetypes>
+
+where ``lib`` is the library in which the archetype came from and ``name`` is
+the archetype name. Let's build our archetypes!
+Using the template below and the table below,
+fill in the template with the variables listed in the table below.
+
++-------------+------------------+----------------------------+
+| Variable    | Value            | Purpose                    |
++=============+==================+============================+
+| ``lib1``    | ``cycamore``     | Library of the archetype   |
++-------------+------------------+----------------------------+
+| ``arch1``   | ``Enrichment``   | Name of archetype          |
++-------------+------------------+----------------------------+
+| ``lib2``    | ``cycamore``     | Library of the archetype   |
++-------------+------------------+----------------------------+
+| ``arch2``   | ``Reactor``      | Name of archetype          |
++-------------+------------------+----------------------------+
+| ``lib3``    | ``cycamore``     | Library of the archetype   |
++-------------+------------------+----------------------------+
+| ``arch3``   | ``Source``       | Name of archetype          |
++-------------+------------------+----------------------------+
+| ``lib4``    | ``cycamore``     | Library of the archetype   |
++-------------+------------------+----------------------------+
+| ``arch4``   | ``Sink``         | Name of archetype          |
++-------------+------------------+----------------------------+
+
+
+Archetype Block Template
+------------------------
+.. code-block:: XML
+
+      <archetypes>
+        <spec>
+          <lib>lib1</lib>
+          <name>arch1</name>
+        </spec>
+        <spec>
+          <lib>lib2</lib>
+          <name>arch2</name>
+        </spec>
+        <spec>
+          <lib>lib3</lib>
+          <name>arch3</name>
+        </spec>
+        <spec>
+          <lib>lib4</lib>
+          <name>arch4</name>
+        </spec>
+      </archetypes>
+
+
+Once complete, your ``archetypes`` block should look like:
+
+.. code-block:: XML
+
+    <archetypes>
+      <spec>
+        <lib>cycamore</lib>
+        <name>Enrichment</name>
+      </spec>
+      <spec>
+        <lib>cycamore</lib>
+        <name>Reactor</name>
+      </spec>
+      <spec>
+        <lib>cycamore</lib>
+        <name>Source</name>
+      </spec>
+      <spec>
+        <lib>cycamore</lib>
+        <name>Sink</name>
+      </spec>
+    </archetypes>
+
+Once complete, append the archetypes section under the control section of input file [#f1]_.
+
+.. rubric:: Footnotes
+
+.. [#f1] The exact order of the sections in a |Cyclus| input file are of minor
+consequence. The ``control`` sequence must go first, but the other sequences
+ can go in any order that makes sense to the user. The traditional organization
+  of an input file is: control, archetypes, commodities, facilities,
+   regions/institutions, and recipes.