From 7b08b945e3f47d9f2dc80918bcc5f5368c4e37ca Mon Sep 17 00:00:00 2001 From: Katie Mummah Date: Wed, 3 Jul 2024 15:47:20 -0500 Subject: [PATCH 1/3] starting to add to toolkit page and starting packaging page --- source/arche/toolkit.rst | 58 +++++++++++++++++++++++++++++++++++ source/user/writing_input.rst | 1 + 2 files changed, 59 insertions(+) diff --git a/source/arche/toolkit.rst b/source/arche/toolkit.rst index 27719d0ec..07077f352 100644 --- a/source/arche/toolkit.rst +++ b/source/arche/toolkit.rst @@ -114,3 +114,61 @@ 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 manages the process of requesting + a particular commodity. + + 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 manages the process of providing + a particular commodity to the DRE. \ No newline at end of file diff --git a/source/user/writing_input.rst b/source/user/writing_input.rst index 5ac25c451..3297ca344 100644 --- a/source/user/writing_input.rst +++ b/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 -------------------- From be8f0d43d1e41c2a5f0af4ef0d2c52a937dd195c Mon Sep 17 00:00:00 2001 From: Katie Mummah Date: Wed, 3 Jul 2024 15:49:56 -0500 Subject: [PATCH 2/3] actually adding the packaging page this time --- source/user/input_specs/package.rst | 137 ++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 source/user/input_specs/package.rst diff --git a/source/user/input_specs/package.rst b/source/user/input_specs/package.rst new file mode 100644 index 000000000..2e9403b21 --- /dev/null +++ b/source/user/input_specs/package.rst @@ -0,0 +1,137 @@ +``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 cyc + +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 + + + pwr_assembly + 615.2 + 615.2 + + +Example (bulk) +++++++++++++++ +This example defines a UF6 cylinder package. + +.. code-block:: xml + + + UF6_cylinder + 1 + 0.8 + first + + +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 + + + UF6_flatrack + 3 + 4 + hybrid + + +.. rst-class:: html-toggle + +Grammar Definition +++++++++++++++++++ + +**Packaging XML:** + +.. code-block:: xml + + + + + + + + + + + +**Transport Unit XML:** + +.. code-block:: xml + + + + + + + + + \ No newline at end of file From ee28a93d57c413178936dd3af6b28be39d45b2cb Mon Sep 17 00:00:00 2001 From: Katie Mummah Date: Mon, 15 Jul 2024 12:09:53 -0500 Subject: [PATCH 3/3] more text on buy/sell and package --- source/arche/toolkit.rst | 81 +++++++++++++++++++++++++++-- source/user/input_specs/package.rst | 4 +- 2 files changed, 80 insertions(+), 5 deletions(-) diff --git a/source/arche/toolkit.rst b/source/arche/toolkit.rst index 07077f352..c295e9f5c 100644 --- a/source/arche/toolkit.rst +++ b/source/arche/toolkit.rst @@ -126,8 +126,38 @@ Multi-Resource Buffer Inventory Tracker [C++] Material Buy Policy Class [C++] +++++++++++++++++++++++++++++++ - The ``cyclus::toolkit::MatlBuyPolicy`` class manages the process of requesting - a particular commodity. + 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 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: @@ -170,5 +200,48 @@ Material Buy Policy Class [C++] Material Sell Policy Class [C++] ++++++++++++++++++++++++++++++++ - The ``cyclus::toolkit::MatlSellPolicy`` class manages the process of providing - a particular commodity to the DRE. \ No newline at end of file + 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 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. \ No newline at end of file diff --git a/source/user/input_specs/package.rst b/source/user/input_specs/package.rst index 2e9403b21..f19f17738 100644 --- a/source/user/input_specs/package.rst +++ b/source/user/input_specs/package.rst @@ -9,7 +9,9 @@ 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 cyc +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: