Add toolkit classes and Packaging page

source/arche/toolkit.rst

@@ -114,3 +114,134 @@ 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.
+
+Multi-Resource Buffer Inventory Tracker [C++]
++++++++++++++++++++++++++++++++++++++++++++++
+  The ``cyclus::toolkit::TotalInvTracker`` class tracks the total quantity of
+  resources held across multiple Resource Buffers. The Tracker may have a 
+  total inventory limit separate from any individual Resource Buffer limits. 
+
+  Implementing a tracker can be useful in replicating a facility-wide limit. 
+  A TotalInvTracker is required to initialize the Material Buy Policy.
+
+Material Buy Policy Class [C++]
++++++++++++++++++++++++++++++++
+  The ``cyclus::toolkit::MatlBuyPolicy`` class performs semi-automatic 
+  inventory management of a material buffer .
+  For simple behavior, policies virtually eliminate the need to write any code
+  for resource exchange. Just assign a few policies to work with a few buffers
+  and focus on writing the physics and other behvavior of your agent. Typical
+  usage goes something like this:
+
+  .. code-block:: c++
+    class YourAgent : public cyclus::Facility {
+    public:
+      ...
+
+      void EnterNotify() {
+        cyclus::Facility::EnterNotify(); // always do this first
+
+        policy_.Init(this, &inbuf_, "inbuf-label").Set(incommod, comp).Start();
+      }
+      ...
+
+    private:
+      MatlBuyPolicy policy_;
+      ResBuf<Material> inbuf_;
+      ...
+    }
+
+
+  The policy needs to be initialized with its owning agent and the material
+  buffer that is is managing. It also needs to be activated by calling the
+  Start function for it to begin participation in resource exchange.  And
+  don't forget to add some commodities to request by calling Set. All policy
+  configuration should usually occur in the agent's EnterNotify member
+  function.
+
+  The following inventory management strategies are available:
+
+  * Active and dormant cycles. Developer must create two random distributions 
+    using the ``cyclus::RandomNumberGenerator`` class. The active distribution is
+    sampled to determine the length of time steps that the agent will be actively 
+    requesting its incommodity. The dormant distribution is sampled to determine
+    the length of time steps that the agent will be dormant, placing no requests
+    regardless of whether inventory space is available at the time.
+
+  * Cumulative capacity. Cumulative capacity is a type of active-dormant cycle
+    where the active phase is determined not by sampling from a random distribution,
+    but by the cumulative quantity of incommodity that the agent has received 
+    during this cycle. The facility will stay active until the cumulative quantity
+    is reached, at which point it will enter the dormant phase. The dormant 
+    phase functions exactly as in the active-dormant cycle.
+
+  * Buying size distribution. Similar to active and dormant cycles, the size of
+    request placed by an agent can be determined by a random distribution. The
+    sampled value is a fraction of the maximum available request, which is 
+    determined by the throughput and inventory space available both in the receiving
+    ``ResBuf`` and in the entire facility, using the ``TotalInvTracker``.
+
+  * Quantized buying. The agent can be set to request a fixed quantity of its
+    incommodity, when space allows. It will not accept partial fulfillment of its
+    request.
+
+  * Inventory policies. Two standard inventory policies are available, called
+    reorder point-reorder quantity or (R,Q), and minimum-maximum or (s,S). The
+    ``inv_policy`` parameter must be set to either "RQ" or "sS" to use these. Two
+    additional parameters determine the behavior, ``req_at`` and ``fill_behav``. 
+    For both policies, ``req_at`` is the inventory quantity at which new 
+    incommodity should be ordered. Above this point, the agent will not place a
+    request. Below this point, the agent will place a request. For the (R,Q)
+    policy, ``fill_behav`` is the Q, or quantity of incommodity that the agent 
+    will request. This functions similar to quantized buying, where the agent
+    seeks to buy exactly Q / ``fill_behav`` quantity of incommodity. For the (s,S)
+    policy, ``fill_behav`` is the S, or the maximum quantity of incommodity that
+    the agent will accept. The agent will request S minus the current inventory.
+
+Material Sell Policy Class [C++]
+++++++++++++++++++++++++++++++++
+  The ``cyclus::toolkit::MatlSellPolicy`` class performs semi-automatic inventory 
+  management of a material buffer by making offers and trading away materials 
+  in an attempt to empty the buffer's inventory every time step.
+
+  For simple behavior, policies virtually eliminate the need to write any code
+  for resource exchange. Just assign a few policies to work with a few buffers
+  and focus on writing the physics and other behvavior of your agent.  Typical
+  usage goes something like this:
+
+  .. code-block:: c++
+    class YourAgent : public Facility {
+      public:
+        ...
+
+        void EnterNotify() {
+          Facility::EnterNotify(); // always do this first
+
+          policy_.Init(this, &outbuf_, "outbuf-label", ...).Set(outcommod).Start();
+        }
+        ...
+
+       private:
+        MatlSellPolicy policy_;
+        ResBuf<Material> outbuf_;
+         ...
+    }
+
+  The policy needs to be initialized with its owning agent and the material
+  buffer that is is managing. It also needs to be activated by calling the
+  Start function for it to begin participation in resource exchange.  And
+  don't forget to add some commodities to offer on by calling Set.  All policy
+  configuration should usually occur in the agent's EnterNotify member
+  function.
+
+  When a policy's managing agent is deallocated, you MUST either
+  call the policy's Stop function or delete the policy. Otherwise SEGFAULT.
+
+  ``MatlSellPolicy`` can be initialized with a package and transport unit.
+  When responding to requests for bids, the policy will only offer resources
+  in quantities that can be packaged (and placed into transport units, if
+  applicable). The packaging process occurs only after trades have been accepted,
+  in the case that partial trades are accepted. Note that partial acceptance of
+  bids may result in "failed" trades where the accepted amount cannot be packaged
+  and thus only a portion of the bid gets packaged and sent to the receiving
+  agent.

source/user/input_specs/package.rst

@@ -0,0 +1,139 @@
+``Package`` and ``TransportUnit`` - Package and Transport Unit Definition (optional, may appear multiple times)
+================================================================================================================
+
+Package types are a fundamental parameter of resources in Cyclus, with a 
+default of ``unpackaged``, with no restrictions. The user can define their own
+package types as well. Currently, packaging is available in the Material Sell
+Policy (see Cyclus Toolkit), and is implemented in the Cycamore:Storage 
+facility archetype; Storage re-packages outgoing commodidies as they are being
+traded to another agent.
+
+Packaging is currently available in the Material Sell Policy (see Cyclus Toolkit),
+and is implemented in cycamore:Storage. Storage makes bids on its outcommodity
+based on its packaging restrictions and re-packages outgoing commodidies
+as they are being traded to another agent.
+
+A ``package`` block has the following sections:
+
+  * ``name`` (required once) - the unique name for this type of packaging
+
+  * ``fill_min`` - the minimum amount of material that can be in the package
+    (default: 0)
+
+  * ``fill_max`` - the maximum amount of material that can be in the package
+    (default: infinity)
+
+  * ``strategy`` - The algorithm used to determine the quantity of material 
+    placed in a package when more than ``fill_max`` is available to package.
+    Current options are:
+
+        * ``first`` - Packages are filled up to the ``fill_max`` one by one, 
+          until less than ``fill_min`` is left to package. 
+        * ``equal`` - Given the amount of material available to package, 
+          all packages are filled to the same level.
+
+Example (item)
+++++++++++++++
+This example defines a PWR fuel assembly package. Item packages (where the 
+``fill_min`` and ``fill_max`` are the same) do not need to specify the 
+``strategy`` value.
+
+.. code-block:: xml
+
+  <package>
+    <name>pwr_assembly</name>
+    <fill_min>615.2</fill_min>
+    <fill_max>615.2</fill_max>
+  </package>
+
+Example (bulk)
+++++++++++++++
+This example defines a UF6 cylinder package.
+
+.. code-block:: xml
+
+  <package>
+    <name>UF6_cylinder</name>
+    <fill_min>1</fill_min>
+    <fill_max>0.8</fill_max>
+    <fill_strategy>first</fill_strategy>
+  </package>
+
+TransportUnit
++++++++++++++
+
+Transport units are a way to furhter restrict the movement of resources in a
+simulation. Unlike packages (above), ``TransportUnit``s are not a parameter of
+resources, but rather a restriction available in the Material Sell Policy
+(see Cyclus Toolkit) to restrict trades to an integer number of packages.
+
+A ``TransportUnit`` block has the following sections:
+
+  * ``name`` (required once) - the unique name for this type of transport unit
+
+  * ``fill_min`` - the minimum number of packages that can be in the transport
+    unit, integer (default: 0)
+
+  * ``fill_max`` - the maximum number of packages that can be in the transport 
+    unit, integer (default: infinity)
+
+  * ``strategy`` - the algorith used to determine the number of packages placed
+    in a transport unit when more than ``fill_max`` are available to package.
+    Current options are:
+
+        * ``first`` - Transport units are filled up to the ``fill_max`` one by
+          one, until less than ``fill_min`` is left to package.
+        * ``equal`` - Given the number of packages available to package, all
+          transport units are filled to the same level.
+        * ``hybrid`` - Fill transport units iteratively, re-calculating the
+          number of packages to place in each transport unit based on the
+          remaining packages. More efficient than ``equal`` or ``first`` at
+          sending the maximum number of packages.
+
+Transport Unit Example
++++++++++++++++++
+This example requires that three or four UF6 cylinders be shipped in the same
+flatrack.
+
+**XML:**
+
+.. code-block:: xml
+
+    <transportunit>
+        <name>UF6_flatrack</name>
+        <fill_min>3</fill_min>
+        <fill_max>4</fill_max>
+        <strategy>hybrid</strategy>
+    </transportunit>
+
+.. rst-class:: html-toggle
+
+Grammar Definition
+++++++++++++++++++
+
+**Packaging XML:**
+
+.. code-block:: xml
+
+    <element name="package">
+      <interleave>
+        <element name="name"><text/></element>
+        <element name="fill_min"><data type="double"/></element>
+        <element name="fill_max"><data type="double"/></element>
+        <element name="strategy"><text/></element>
+      </interleave>
+    </element>
+
+
+**Transport Unit XML:**
+
+.. code-block:: xml
+
+    <element name="transportunit">
+      <interleave>
+        <element name="name"><text/></element>
+        <element name="fill_min"><data type="nonNegativeInteger"/></element>
+        <element name="fill_max"><data type="nonNegativeInteger"/></element>
+        <element name="strategy"><text/></element>
+      </interleave>
+    </element>

source/user/writing_input.rst

@@ -135,6 +135,7 @@ any order in the input file:
    input_specs/region
    input_specs/inst
    input_specs/recipe
+   input_specs/package
 
 Including XML Files
 --------------------