From 7a3844eeef3bdf837fae00210d0d364ad69eec81 Mon Sep 17 00:00:00 2001 From: Bachmann Date: Mon, 27 Oct 2025 16:18:43 -0500 Subject: [PATCH 01/26] remove mention of internet connection --- source/user/tutorial/index.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/user/tutorial/index.rst b/source/user/tutorial/index.rst index a135cc27..c83d0f6f 100644 --- a/source/user/tutorial/index.rst +++ b/source/user/tutorial/index.rst @@ -3,8 +3,7 @@ In this tutorial, we will build, run and analyze a fuel cycle scenario using |Cyclus|, a nuclear fuel cycle simulator. This tutorial assumes that the learner is already -familiar with the purpose of a nuclear fuel cycle simulator. This tutorial will -require an internet connection so that |Cyclus| can be run remotely. +familiar with the purpose of a nuclear fuel cycle simulator. Overview --------- From 19ad825a1776cae3e4aba2fbb763abd9cb0f24f7 Mon Sep 17 00:00:00 2001 From: Bachmann Date: Mon, 27 Oct 2025 16:22:06 -0500 Subject: [PATCH 02/26] consolidate Cyclus and Cycamore to single link --- source/user/tutorial/install_launch_cyclus.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/source/user/tutorial/install_launch_cyclus.rst b/source/user/tutorial/install_launch_cyclus.rst index 3afb59c0..fca3fe73 100644 --- a/source/user/tutorial/install_launch_cyclus.rst +++ b/source/user/tutorial/install_launch_cyclus.rst @@ -2,7 +2,5 @@ Installing and Launching Cyclus =============================== For this tutorial, the |Cyclus|, and Cycamore programs are utilized. You can -install |Cyclus| using the following steps listed on the `Install Cyclus `_ page. -You can install Cycamore from the `Cycamore github repository `_. - - +install both codes using the following steps listed on the +`Install Cyclus `_ page. From e01ca7959e7cf8c20076b2a390ad5a9d903dc262 Mon Sep 17 00:00:00 2001 From: Bachmann Date: Mon, 27 Oct 2025 16:54:12 -0500 Subject: [PATCH 03/26] make edits suggested in #427 --- source/user/tutorial/sim_parm.rst | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/source/user/tutorial/sim_parm.rst b/source/user/tutorial/sim_parm.rst index 2d9b1043..50326b92 100644 --- a/source/user/tutorial/sim_parm.rst +++ b/source/user/tutorial/sim_parm.rst @@ -58,19 +58,20 @@ decay function on them as desired to decay them to the current simulation time. |Cyclus| can operate in 3 decay modes, with 1 additional mode likely to be added in a future release: -- 'never', all decay is turned off -- 'manual', meaning it is only on if the individual archetype decays their own inventory -- 'lazy', which will compute decay only when archetypes fetch a particular composition. -- 'periodic' (future), automatically decays all materials in a simulation with some fixed frequency. + - 'never', all decay is turned off + - 'manual', meaning it is only on if the individual archetype decays their own inventory + - 'lazy', which will compute decay only when archetypes fetch a particular composition. + - 'periodic' (future), automatically decays all materials in a simulation with some fixed frequency. There are other `optional parameters `_ that could be given but are not in the scope of this tutorial. For simplicity, we will not model decay in this tutorial. The lifetime of a |Cyclus| simulation is determined by its `duration`, the -number of timesteps |Cyclus| will model the fuel cycle. |Cyclus| uses a +number of time steps |Cyclus| will model the fuel cycle. |Cyclus| uses a time-step approach to march through time and determine what actions are -taken by each agent at each point in time. Each time step includes the following phases: +taken by each agent at each point in time. Each time step includes +`the following phases `_: * new agents may enter the system (deployment) * each agent prepares for exchange of material @@ -78,12 +79,17 @@ taken by each agent at each point in time. Each time step includes the followin * each agent acts after the exchange of material * agents may leave the system (decommissioning) -This tutorial assumes a time step of 1 month +The length of a time step is not inherently defined in |Cyclus|, the kernel works +on just the notion of a time step. There is the optional `dt` setting in +the `control block `_, in +which a user can set the number of seconds in a time step, which affects the +decay of materials. This tutorial assumes a time step of 1 month, which is the +default value for the `dt` input. Activity: Set Simulation Parameters ----------------------------------- -Using the simulation control template above and the table below, properly fill the template +Using the simulation control template above and the table below, let's fill in the template with the variables listed in the table below in your favorite text editor. +-------------------+---------------+---------------------------------+ From ce47b36f7ad3e0e20168e1bd9995d61e97176de5 Mon Sep 17 00:00:00 2001 From: Bachmann Date: Tue, 28 Oct 2025 08:34:42 -0500 Subject: [PATCH 04/26] make minor revisions, per #427 --- source/user/tutorial/add_arche.rst | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/source/user/tutorial/add_arche.rst b/source/user/tutorial/add_arche.rst index 7cc0dea4..164a33b3 100644 --- a/source/user/tutorial/add_arche.rst +++ b/source/user/tutorial/add_arche.rst @@ -46,7 +46,7 @@ to model facilities that may be at the peripheral of a problem. The Cycamore facility archetypes are: * **Source:** `Source `_ - is a generic source of material may fill the role of any + is a generic source of material that may fill the role of any facility that produces fresh material. Depending on how much of the fuel 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 @@ -70,16 +70,23 @@ facility archetypes are: 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, export of a commodity to outside simulated facilities, etc. +* **Mixer:** `Mixer `_ is +* **Storage:** `Storage `_ +* Activity: Discover the Available Archetypes =========================================== 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. +To check which archetypes are downloaded on your machine run the command ``cyclus -a`` from your terminal. You will notice that there are more archetypes listed than the ones we +have discussed. This is because we have only discussed the facility archetypes so far, +and Cycamore also has `region and institution archetypes `_, which we will discuss later. + +Note: using this command will only show the +`C++-based archetypes `_ that +are available. It will not show any `python-based archetypes `_. + -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 -`_ webpage. What archetypes can you see yourself using in your research? @@ -125,10 +132,13 @@ The ``archetype`` block is located after the simulation control block and takes lib2 arch_2 + ... where ``lib`` is the library in which the archetype came from and ``name`` is -the archetype name. Let's build our archetypes! +the archetype name. You need one `spec` block in the archetypes section +for each archetype you use in your simulation. +Let's build the archetypes block in our input file. Using the template below and the table below, fill in the template with the variables listed in the table below. @@ -200,7 +210,7 @@ Once complete, your ``archetypes`` block should look like: -Once complete, append the archetypes section under the control section of input file [#f1]_. +The order of the archetypes in this block is of minor consequence. Once complete, append the archetypes section under the control section of input file [#f1]_. .. rubric:: Footnotes From 5eac5ecf798ab76881b7f2d4be45f76b2eb4432d Mon Sep 17 00:00:00 2001 From: Bachmann Date: Tue, 28 Oct 2025 09:41:17 -0500 Subject: [PATCH 05/26] minor revisions, per #427 --- source/user/tutorial/add_commod_recipe.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/source/user/tutorial/add_commod_recipe.rst b/source/user/tutorial/add_commod_recipe.rst index de72ef75..08d016f0 100644 --- a/source/user/tutorial/add_commod_recipe.rst +++ b/source/user/tutorial/add_commod_recipe.rst @@ -5,7 +5,8 @@ Concept: Commodities ++++++++++++++++++++ |Cyclus| exchanges resources between facilities using a market-like mechanism -called the **dynamic resource exchange (DRE)**. The concept of a **commodity** is +called the `**dynamic resource exchange (DRE)** `_. +The concept of a **commodity** is used to simply indicate which facilities may be interested in trading with each other through the DRE. A commodity is therefore nothing more than a unique name that is used to define a set of producers and consumers of a @@ -22,7 +23,8 @@ Any potential resource transfer (i.e., a bid or a request) may be denoted as **exclusive**. An exclusive transfer excludes partial fulfillment; it must either be met fully or not at all. This mode supports concepts such as the trading of individual reactor assemblies. In combination -with the notion of mutual requests, complex instances of supply and +with the notion of mutual requests (one request that can be met through multiple +commodities), complex instances of supply and demand are enabled. Finally, requesting facilities, institutions and @@ -30,10 +32,7 @@ regions may apply **preferences** to each potential request-bid pairing based on the proposed resource transfer. Facilities can apply arbitrary complex logic to **rank the bids** that they have received, whether based on the quantity available in each bid or on the quality of each bid, and -the consequent implications of the physics behavior of that facility. In -addition, an institution can apply a higher preference to a partner to -which it is congenial; similarly, a region may negate any transfers of -material which have a higher uranium enrichment than is allowable. +the consequent implications of the physics behavior of that facility. For example, the flow graph below shows three suppliers (left) and two consumers (right), and the potential flows of various commodities among @@ -167,7 +166,7 @@ Concept: Recipes Most commodities are materials, which have a quantity and an isotopic composition. Recipes are the isotopic composition of a certain material. For -example, u_ore has an isotropic composition of 0.711% :math:`^{235}`\ U and +example, u_ore has an isotopic composition of 0.711% :math:`^{235}`\ U and 99.284% :math:`^{238}`\ U. The recipe section of a |Cyclus| input file is typically located at the end of the input and is of the form: @@ -199,9 +198,10 @@ For example, :math:`^{235}`\ U can be expressed as: For more details, reference the `Recipe definition <../input_specs/recipe.html>`_ page. -First, we can declare the isotopic compositions of the fresh and spent -fuel. We'll be using simple recipes: fresh fuel is 4.0% :math:`^{235}`\ U by mass, -remainder U-238. Spent fuel is 1.1% :math:`^{235}`\ U, 94.0% :math:`^{238}`\ U, 0.9% :math:`^{239}`\ Pu, and +For this input file, we need to define three recipes: natural uranium, fresh fuel, +and spent fuel. We'll be using simple recipes: natural uranium is 0.711% +:math:`^{235}`\ U by mass, remainder :math:`^{238}`\ U, fresh fuel is 4.0% :math:`^{235}`\ U by mass, +remainder U-238, and spent fuel is 1.1% :math:`^{235}`\ U, 94.0% :math:`^{238}`\ U, 0.9% :math:`^{239}`\ Pu, and 4.0% :math:`^{137}`\ Cs. Activity: Creating a Recipe From 5f3289c40bd74012e1b9cdf637043f058fb3f305 Mon Sep 17 00:00:00 2001 From: Bachmann Date: Tue, 28 Oct 2025 10:49:06 -0500 Subject: [PATCH 06/26] make formatting more consistent --- source/user/tutorial/add_proto.rst | 183 ++++++++++++++--------------- 1 file changed, 88 insertions(+), 95 deletions(-) diff --git a/source/user/tutorial/add_proto.rst b/source/user/tutorial/add_proto.rst index 6ad8b97c..42e43835 100644 --- a/source/user/tutorial/add_proto.rst +++ b/source/user/tutorial/add_proto.rst @@ -1,31 +1,18 @@ Understanding Prototypes ------------------------ -One key feature of |Cyclus| is its ability to switch between -different models of the facilities within the fuel cycle. These models, -called **archetypes**, may change how the facility interacts with other -facilities or how the physics of the facility are represented. For -example, reactor archetypes determine the reactor's fresh and spent fuel -compositions and how the reactor experiences fuel burn-up. A reactor -model can have three varying fidelity levels: - -* A very simple model that uses recipe to deplete fuel -* A more complex model may tabulate reactor performance and - physics parameters, and interpolate its input and output recipes. -* The most complex model could perform a full depletion calculation each time - new fuel enters the reactor. - -A simple set of archetypes have been created in `Cycamore `__. While the archetype describes the form of the model used to represent a facility, a variety of parameters are generally available to configure the -specific behavior. For the example of a reactor, the developer will probably +specific behavior. For the example of a reactor, the developer will probably allow the user to define the power level of the reactor, independent of the specific model chosen to represent the behavior of the model. Other common reactor parameters are fuel loading parameters such as cycle length and batch size. In |Cyclus|, when an archetype has been configured with a -specific set of parameters, it is called a **prototype**. +specific set of parameters, it is called a `**prototype** `_. You can have multiple prototypes that use the same +archetype, and you can have multiple deployments of the same prototype in +a simulation. Example: Source Prototype +++++++++++++++++++++++++ @@ -34,8 +21,9 @@ time step) capacity and a lifetime capacity defined by a total inventory size. It offers its material as a single commodity. If a composition recipe is specified, it provides that single material composition to requesters. If unspecified, the source provides materials with the exact requested compositions. -The inventory size and throughput both default to infinite. Supplies material -results in corresponding decrease in inventory, and when the inventory size +The inventory size and throughput both default to infinite. Supplying material +from the Source prototype +results in a corresponding decrease in inventory, and when the inventory size reaches zero, the source can provide no more material. The Source archetype is of the form: @@ -46,25 +34,25 @@ The Source archetype is of the form: Source - out_commodity + [string] Optional parameters: -outrecipe: +``outrecipe``: Name of the isotopic composition of the material that this source provides regardless of the requested composition. If empty, the Source creates and provides whatever composition is requested. .. code-block:: XML - [outrecipe] + [string] -inventory_size: default = 1e+299, range: [0.0, 1e+299] +``inventory_size``: default = 1e+299, range: [0.0, 1e+299] Total amount of material this source has remaining. Every trade decreases this value by the supplied material quantity. When it reaches zero, the source cannot provide any more material. @@ -73,7 +61,7 @@ inventory_size: default = 1e+299, range: [0.0, 1e+299] [double ( kg )] -throughput: default=1e+299,range: [0.0, 1e+299] +``throughput``: default=1e+299,range: [0.0, 1e+299] Amount (kg) of the commodity that the Source can supply at each time step .. code-block:: xml @@ -83,7 +71,7 @@ throughput: default=1e+299,range: [0.0, 1e+299] Activity: Configure the Source prototype ++++++++++++++++++++++++++++++++++++++++ Our source, ``UraniumMine``, will provide the natural uranium ore for our enrichment facility. -This facility takes two inputs, ``name`` and ``outcommd``. Using the Source +This facility takes two inputs, ``name`` and ``outcommod``. Using the Source Archetype and the table below, create the UraniumMine prototype. +-----------------------+---------------------------+ @@ -93,7 +81,7 @@ Archetype and the table below, create the UraniumMine prototype. +-----------------------+---------------------------+ | ``Archetype`` | ``Source`` | +-----------------------+---------------------------+ -| ``out_commod`` | ``u_ore`` | +| ``out_commodity | ``u_ore`` | +-----------------------+---------------------------+ 1. The template for the Source archetype is of the form: @@ -104,13 +92,13 @@ Archetype and the table below, create the UraniumMine prototype. name - outcommod - + out_commodity + 2. Filling in the variables ``name``, ``Archetype``, and ``out_commod`` as -``UraniumMine``, ``Source``, and ``fresh_uox`` leads to: +``UraniumMine``, ``Source``, and ``u_ore`` leads to: .. code-block:: XML @@ -139,52 +127,52 @@ The Enrichment archetype is of the form: EnrichmentPlant - feed_commodity - feed_recipe - product_commodity - tails_commodity + [string] + [string] + [string] + [string] Optional parameters: -max_feed_inventory: default = 1e+299, range: [0.0, 1e+299] +``max_feed_inventory``: default = 1e+299, range: [0.0, 1e+299] Maximum total inventory of natural uranium in the enrichment facility (kg) .. code-block:: XML - 1000000 + [double (kg)] -tails_assay: default=0.003, range: [0.0, 0.003] +``tails_assay``: default=0.003, range: [0.0, 0.003] Tails assay from the enrichment process .. code-block:: XML [double] -initial_feed: default = 0 +``initial_feed``: default = 0 Amount of natural uranium stored at the enrichment facility at the beginning of the simulation (kg) .. code-block:: XML [double] -max_enrich: default = 1.0, range: [0.0,1.0] +``max_enrich``: default = 1.0, range: [0.0,1.0] maximum allowed weight fraction of U235 in product .. code-block:: XML [double] -order_prefs: default = 1, userlevel: 10 - Turn on preference ordering for input material so that EF chooses higher U235 content first +``order_prefs``: default = 1, userlevel: 10 + Turn on preference ordering for input material so that enrichment facility chooses higher U235 content first .. code-block:: XML [boolean] -swu_capacity: default = 1e+299, range: [0.0, 1e+299] +``swu_capacity``: default = 1e+299, range: [0.0, 1e+299] Separative work unit (SWU) capacity of enrichment facility (kgSWU/timestep) .. code-block:: XML @@ -200,14 +188,14 @@ The template for the Enrichment archetype is of the form: .. code-block:: XML - enrichment_plant_name + name feed_commodity feed_recipe product_commodity tails_commodity - 1000000 + max_feed_inventory @@ -221,13 +209,13 @@ Using the template above and the table below, generate the input enrichment faci +-------------------------+---------------------------+ | ``Archetype`` | ``Enrichment`` | +-------------------------+---------------------------+ -| ``feed_commod`` | ``u_ore`` | +| ``feed_commodity`` | ``u_ore`` | +-------------------------+---------------------------+ | ``feed_recipe`` | ``nat_u`` | +-------------------------+---------------------------+ -| ``product_commod`` | ``fresh_uox`` | +| ``product_commodity`` | ``fresh_uox`` | +-------------------------+---------------------------+ -| ``tails_commod`` | ``tails`` | +| ``tails_commodity`` | ``tails`` | +-------------------------+---------------------------+ | ``max_feed_inventory`` | 1000000 | +-------------------------+---------------------------+ @@ -263,9 +251,9 @@ from its original fresh fuel composition into its spent fuel form. Each fuel is identified by a specific input commodity and has an associated input recipe (nuclide composition), output recipe, output commodity, and preference. The preference identifies which input fuels are preferred -when requesting. Changes in these preferences can be specified as a function of time using the pref_change +when requesting. Changes in these preferences can be specified as a function of time using the ``pref_change`` variables. Changes in the input-output recipe compositions can also be specified as a function of time using -the recipe_change variables. +the ``recipe_change`` variables. The reactor treats fuel as individual assemblies. Fuel is requested in assembly-sized quanta. If real-world assembly modeling is unnecessary, parameters can be adjusted (e.g. ``n_assem_core``, ``assem_size``, @@ -286,28 +274,31 @@ The Reactor archetype is of the form: - input_fuel_commodity + [string] - input_fuel_recipe + [string] - output_fuel_commodity + [string] - output_fuel_recipe + [string] - 18 - 1 - 33000 - 3 - 1 - power_out + [int] + [int] + [double] + [int] + [int] + [double] +There are many optional input parameters to the Cycamore Reactor archetype. +We advise exploring the `Reactor archetype documentation `_ to find them all. + Activity: Creating the Reactor Prototype ++++++++++++++++++++++++++++++++++++++++ @@ -319,29 +310,29 @@ The template for the reactor is given below: .. code-block:: XML - Reactor + name - [VALUE] - [VALUE] - [VALUE] - [VALUE] - [VALUE] - [VALUE] - [VALUE] - [VALUE] - [VALUE] - [VALUE] - + in_commod1 + in_recipe1 + out_commod1 + out_recipe1 + cycle_length + refuel_length + assem_mass + n_core + n_batch + power + Where: -* ``fuel_incommods``: input fuel commodity -* ``fuel_inrecipes``" input fuel recipe -* ``fuel_outcommods``: output fuel commodity -* ``fuel_outrecipes``: output fuel recipe. +* ``fuel_incommods``: input fuel commodity -- you can list more than one by adding more ``val`` blocks +* ``fuel_inrecipes``" input fuel recipe -- you can list more than one +* ``fuel_outcommods``: output fuel commodity -- you can list more than one +* ``fuel_outrecipes``: output fuel recipe -- you can list more than one * ``cycle_time``: amount of time the reactor operates between refueling outages * ``refuel_time``: duration of refueling outage * ``assem_size``" size of a single assembly @@ -358,25 +349,25 @@ Using the template above and the table below, create the Reactor prototype. +-----------------------+---------------------------+ | ``Archetype`` | ``Reactor`` | +-----------------------+---------------------------+ -| ``fuel_incommods`` | ``fresh_uox`` | +| ``in_commod1`` | ``fresh_uox`` | +-----------------------+---------------------------+ -| ``fuel_inrecipes`` | ``fresh_uox`` | +| ``in_recipe1`` | ``fresh_uox`` | +-----------------------+---------------------------+ -| ``fuel_outcommods`` | ``spent_uox`` | +| ``out_commod1`` | ``spent_uox`` | +-----------------------+---------------------------+ -| ``fuel_outrecipes`` | ``spent_uox`` | +| ``out_recipe1`` | ``spent_uox`` | +-----------------------+---------------------------+ -| ``cycle_time`` | ``18`` | +| ``cycle_length`` | ``18`` | +-----------------------+---------------------------+ -| ``refuel_time`` | ``1`` | +| ``refuel_length`` | ``1`` | +-----------------------+---------------------------+ -| ``assem_size`` | ``33000`` | +| ``assem_mass`` | ``33000`` | +-----------------------+---------------------------+ -| ``n_assem_core`` | ``3`` | +| ``n_core`` | ``3`` | +-----------------------+---------------------------+ -| ``n_assem_batch`` | ``1`` | +| ``n_batch`` | ``1`` | +-----------------------+---------------------------+ -| ``power_cap`` | ``1178`` | +| ``power`` | ``1178`` | +-----------------------+---------------------------+ Once completed, your prototype should look like: @@ -420,8 +411,9 @@ The Sink archetype section is of the form: - input_commodity - input_commodity + [string] + [string] + ... @@ -429,7 +421,7 @@ The Sink archetype section is of the form: Optional parameters: -in_commod_prefs: default=[], range: [None, [1e-299, 1e+299]] +``in_commod_prefs``: default=[], range: [None, [1e-299, 1e+299]] Commodities that the sink facility accepts .. code-block:: XML @@ -437,24 +429,25 @@ in_commod_prefs: default=[], range: [None, [1e-299, 1e+299]] [double] [double] + ... -recipe_name: default=”” +``recipe_name``: default=”” Name of recipe to use for material requests, where the default (empty string) is to accept everything .. code-block:: XML - [inrecipe] + [string] -max_inv_size: default=1e+299, range: [0.0, 1e+299] +``max_inv_size``: default=1e+299, range: [0.0, 1e+299] Total maximum inventory size of sink facility .. code-block:: XML [double] -capacity: default = 1e+299, range: [0.0, 1e+299] +``capacity``: default = 1e+299, range: [0.0, 1e+299] capacity the sink facility can accept at each time step .. code-block:: XML @@ -474,9 +467,9 @@ create the UraniumMine prototype. +-------------------------+---------------------------+ | ``Archetype`` | ``Sink`` | +-------------------------+---------------------------+ -| ``val`` | ``spent_uox`` | +| ``input_commodity1`` | ``spent_uox`` | +-------------------------+---------------------------+ -| ``val`` | ``tails`` | +| ``input_commodity2`` | ``tails`` | +-------------------------+---------------------------+ The sink facility archetype is: @@ -488,8 +481,8 @@ The sink facility archetype is: - input_commodity - input_commodity + input_commodity1 + input_commodity2 From 0481e5fe59ddab27914bf5c854a60030efdf4c6d Mon Sep 17 00:00:00 2001 From: Bachmann Date: Tue, 28 Oct 2025 13:55:59 -0500 Subject: [PATCH 07/26] changes, per #427, includes some reordering --- source/user/tutorial/add_reg_inst.rst | 167 +++++++++++++++----------- 1 file changed, 94 insertions(+), 73 deletions(-) diff --git a/source/user/tutorial/add_reg_inst.rst b/source/user/tutorial/add_reg_inst.rst index b6ecb870..3b6b72f4 100644 --- a/source/user/tutorial/add_reg_inst.rst +++ b/source/user/tutorial/add_reg_inst.rst @@ -8,19 +8,23 @@ Concept: Regions & Institutions Institution agents that exist within a Region agent. This series of ownership allow for control of the interaction behavior between agents. For example, two facilities -may not be allowed to trade if they are in two different regions. +may not be allowed to trade if they are in two different regions. For commodities, +an institution can apply a higher preference for transactions within the +same institution; similarly, a region may negate any transfers of +material which have a higher uranium enrichment than is allowable. Every |Cyclus| simulation needs at least one Region and one Institution, and in this case, we'll use the simplest options: -* a Null Institution (*NullInst*) that holds a set of facilities that are +* a Null Institution (``NullInst``) that holds a set of facilities that are deployed at the start of a simulation. -* a Null Region (*NullRegion*) that holds a set of Institutions. +* a Null Region (``NullRegion``) that holds a set of Institutions. Defining these is done in the archetypes section of the code. This is done in a similar manner as the other archetypes previously defined, except regions -and insitutions used in this tutorial come from the ``agents`` library, rather -than the ``cycamore`` library. +and institutions used in this tutorial come from the ``agents`` library, rather +than the ``cycamore`` library. The ``agents`` library comes with Cyclus, and +you can run ``cyclus --a`` to check that the archetypes are installed. Using the template and table below, properly fill the template with the variables listed in the table below. @@ -53,7 +57,7 @@ simulation. -Once complete, your `agent` Archetypes block should be: +Once complete, your ``agent`` section of the Archetypes block should be: .. code-block:: XML @@ -70,7 +74,7 @@ Once complete, your `agent` Archetypes block should be: Since these are all archetypes, no matter what library they're from, we must append -these two``spec`` blocks into the the arechtype block that we already have. This +these two``spec`` blocks into the the archetype block that we already have. This results in the full archetype block: .. code-block:: XML @@ -109,7 +113,7 @@ Concept: Regions Regions tie together a fuel cycle as they designate what facilities are in the region's fuel cycle. Regions may apply preferences to each potential request-bid pairing based on the proposed resource transfer. -The basic structure of a region is: +The basic structure of the ``NullRegion`` is: .. code-block:: XML @@ -133,7 +137,7 @@ Where: In between the two dotted lines is where the institution and facility information goes. -Concept: Institution +Concept: Institutions ----------------------------------------------------------------------- In |Cyclus| input files, each institution block defines an agent that acts as an institution in the simulation. An institution block can only @@ -166,6 +170,7 @@ Put together, the institution block is the form: Prototype_name number_of_prototype_names + ... Inst_name @@ -173,19 +178,19 @@ Put together, the institution block is the form: -There can be multiple ``entry`` blocks within the same institution. +There can be multiple ``entry`` blocks within the same institution, hence the +``...`` in the block. Multiple entry blocks means that multiple prototypes +are deployed at the start of the simulation. -The example below -introduces two institution agents (the region section that encloses them -is not shown). The first institution has the name *SingleInstitution*, -and is configured from the archetype with the name -``NullInst``. +It is possible to have two institutions in the same region, as shown in the +example input block below. The first institution has the name ``SingleInstitution``, +and is configured from the archetype with the name ``NullInst``. The ``NullInst`` has no defined archetype-specific data. This institution begins the simulation with two facility agents, one based on the ``FacilityA`` prototype and another based on the ``FacilityB`` prototype. The second institution has the -name *AnotherInstitution*, is also configured from the archetype with +name ``AnotherInstitution``, is also configured from the archetype with the name (or alias) ``NullInst``. This institution has no initial facilities. @@ -215,7 +220,7 @@ facilities. -Putting it all together, a complete region template is of the form: +Putting a region and institution blocks together, a complete region template is of the form: .. code-block:: XML @@ -246,18 +251,26 @@ Using the template below, let's create the region section of our input file. .. code-block:: XML - [VALUE] + region_name - [VALUE] - [VALUE] + prototype1 + amount1 + + + prototype2 + amount2 + + + prototype3 + amount3 - [VALUE] + institution_name @@ -270,18 +283,19 @@ region's fuel cycle. In our example, these facilities are the above exercise and the table below, fill out the rest of the region template. -+-----------------+-----------------------------+----------+ -| Variable | Name | Amount | -+=================+=============================+==========+ -| ``prototype`` | ``UraniumMine`` | ``1`` | -+-----------------+-----------------------------+----------+ -| ``prototype`` | ``EnrichmentPlant`` | ``1`` | -+-----------------+-----------------------------+----------+ -| ``prototype`` | ``NuclearRepository`` | ``1`` | -+-----------------+-----------------------------+----------+ -| ``name`` | ``United States Nuclear`` | ``1`` | -+-----------------+-----------------------------+----------+ - ++-----------------------+-----------------------------+----------+ +| Variable | Name | Amount | ++=======================+=============================+==========+ +| ``prototype`` | ``UraniumMine`` | ``1`` | ++-----------------------+-----------------------------+----------+ +| ``prototype`` | ``EnrichmentPlant`` | ``1`` | ++-----------------------+-----------------------------+----------+ +| ``prototype`` | ``NuclearRepository`` | ``1`` | ++-----------------------+-----------------------------+----------+ +| ``institution_name`` | ``United States Nuclear`` | N/A | ++-----------------------+-----------------------------+----------+ +| ``region_name`` | ``USA`` | N/A | ++-----------------------+-----------------------------+----------+ Check: Complete Region block +++++++++++++++++++++++++++++++++++ @@ -289,7 +303,7 @@ Check: Complete Region block .. code-block:: XML - region1 + USA @@ -322,26 +336,22 @@ Activity: Save your input file Save your input file as ``cyclus_intro_file.xml`` -Activity: Add an extra insitution into the Region +Activity: Add an extra institution into the Region ------------------------------------------------- -Having multiple insitutions help organize facilities and their affiliation. -Let's create region, ``USA``, that contains two institutions, ``Exelon`` and ``United States Nuclear``. -``Exelon`` is the institution that holds the ``1178MWe BRAIDWOOD_1`` reactor and ``United States Nuclear`` holds the ``UraniumMine``, ``EnrichmentPlant``, and ``NuclearRepository``. +Having multiple institutions help organize facilities and their affiliation. +In our ``USA`` region, let's add a second institution called ``Exelon``. +``Exelon`` is the institution that holds the ``1178MWe BRAIDWOOD_1`` prototype and ``United +States Nuclear`` holds the ``UraniumMine``, ``EnrichmentPlant``, and ``NuclearRepository`` +prototypes. .. image:: RIF_tutorial.png Using the template above and the table below, let's build the region. -1. Since there are two institutions, ``Exelon`` and ``United States Nuclear``, we will split the region into two parts. -Let's first build the ``Exelon`` institution. This institution has one ``1178MWe BRAIDWOOD_1`` prototype. Using this information we can write this institution as: +1. Let's build the ``Exelon`` institution. This institution has one ``1178MWe BRAIDWOOD_1`` prototype. Using this information we can write this institution as: .. code-block:: XML - - USA - - - @@ -355,32 +365,7 @@ Let's first build the ``Exelon`` institution. This institution has one ``1178MWe -2. Now let's build the second institution, ``United States Nuclear``. This institution has one ``UraniumMine`` prototype, ``EnrichmentPlant`` prototype, and one ``NuclearRepository`` prototype. Using this information we can write this institution as: - -.. code-block:: XML - - - - - UraniumMine - 1 - - - EnrichmentPlant - 1 - - - NuclearRepository - 1 - - - United States Nuclear - - - - - -3. We will close the region section by appending the two sections together and appending a ```` tag to the end of the section. Once complete, your region prototype should look like: +1. We have our ``USA`` region block with the ``United States Nuclear`` institution. This institution has one ``UraniumMine`` prototype, ``EnrichmentPlant`` prototype, and one ``NuclearRepository`` prototype: .. code-block:: XML @@ -392,16 +377,39 @@ Let's first build the ``Exelon`` institution. This institution has one ``1178MWe - 1178MWe BRAIDWOOD_1 + UraniumMine + 1 + + + EnrichmentPlant + 1 + + + NuclearRepository 1 - Exelon + United States Nuclear + + + + + +3. We will add the ``Exelon`` institution into the blank lines of our ``USA`` region + block. Once complete, your region prototype should look like: + +.. code-block:: XML + + + USA + + + @@ -422,6 +430,19 @@ Let's first build the ``Exelon`` institution. This institution has one ``1178MWe + + + + + 1178MWe BRAIDWOOD_1 + 1 + + + Exelon + + + + Activity: Save your Input File From b0e0aaf00943ab49200f909e84ace0f79dfe2ee8 Mon Sep 17 00:00:00 2001 From: Bachmann Date: Tue, 28 Oct 2025 14:07:58 -0500 Subject: [PATCH 08/26] remove cloud paragraph, add terminal running --- source/user/tutorial/run_cyclus_native.rst | 31 ++++++++++++++-------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/source/user/tutorial/run_cyclus_native.rst b/source/user/tutorial/run_cyclus_native.rst index 20ece1a9..de4d8c82 100644 --- a/source/user/tutorial/run_cyclus_native.rst +++ b/source/user/tutorial/run_cyclus_native.rst @@ -1,23 +1,32 @@ Working with |Cyclus| in on your machine ====================================== -Choosing Where to Run ---------------------- - -|Cyclus| can be used to run simulations on your local -machine, if you have |Cyclus| installed, or in an appropriately configured -cloud resource. The advantage of using a local machine is that you can -control which archetypes are available. The advantage of using a remote -machine is that you don't have to install the entire |Cyclus| toolset on your -local machine. - -For this tutorial, |Cyclus| has been installed natively so it can be +For this tutorial, |Cyclus| has been installed on your local machine so it can be run from either the IPython notebook or in the command prompt: .. image:: cyclus_in_IP.png :align: center :alt: Running |Cyclus| in an IPython Notebook +Command Line Execution +---------------------- +Running Cyclus from the command line requires running the command + +.. code-block:: bash + $ cyclus + + +You can view all of the input flags for this command by running + +.. code-block:: bash + $ cyclus -h + + +Some of the common input flags include: +* ``-i arg`` to identify the input file name +* ``-o arg`` to specify the name of the output file to write to (default is ``cyclus.sqlite``) +* ``-v arg`` to specify log verbosity fromm 0 (quiet, default) to 11 (verbose) + Brief Introduction to Jupyter Notebook -------------------------------------- From 7d653d954a713f66e0e0902ea8f7fe753a8b5100 Mon Sep 17 00:00:00 2001 From: Bachmann Date: Tue, 28 Oct 2025 14:19:13 -0500 Subject: [PATCH 09/26] add note about insts deploying prototypes --- source/user/tutorial/add_reg_inst.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/source/user/tutorial/add_reg_inst.rst b/source/user/tutorial/add_reg_inst.rst index 3b6b72f4..ed7601c0 100644 --- a/source/user/tutorial/add_reg_inst.rst +++ b/source/user/tutorial/add_reg_inst.rst @@ -139,8 +139,8 @@ is where the institution and facility information goes. Concept: Institutions ----------------------------------------------------------------------- -In |Cyclus| input files, each institution block defines an agent that -acts as an institution in the simulation. An institution block can only +In |Cyclus| input files, each institution controls the deployment of +the prototypes in the simulation, among other things. An institution block can only appear within a region block. Each institution block has the following sections in any order: @@ -445,6 +445,11 @@ Using the template above and the table below, let's build the region. + +We now have a complete region block. It is possible to have prototypes +defined in your input file that are not listed in an institution. When +that occurs, the prototypes are not deployed in the simulation. + Activity: Save your Input File ------------------------------ From 7e891e539a5802e6984c9961e825d45aa8c53a67 Mon Sep 17 00:00:00 2001 From: Bachmann Date: Tue, 28 Oct 2025 14:23:30 -0500 Subject: [PATCH 10/26] changes per #427 --- source/user/tutorial/add_arche_commod_recipe.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/user/tutorial/add_arche_commod_recipe.rst b/source/user/tutorial/add_arche_commod_recipe.rst index c7b15082..1c5e9ae3 100644 --- a/source/user/tutorial/add_arche_commod_recipe.rst +++ b/source/user/tutorial/add_arche_commod_recipe.rst @@ -2,15 +2,15 @@ Getting Started on Recycle ============================ This exercise will start with some simple activities based on what you learned -in the first exercise. +in the first exercise, using the second input file you made. Activity: Adding Archetypes ----------------------------- We will need two additional archetypes: -1. Add the *cycamore FuelFab* archetype -2. Add the *cycamore Separations* archetype +1. Add the ``cycamore FuelFab`` archetype +2. Add the ``cycamore Separations`` archetype Activity: Adding Commodities ----------------------------- @@ -18,14 +18,14 @@ Activity: Adding Commodities We will need 4 additional commodities: 1. Fresh-MOX-Fuel -2. Used-MOx-Fuel +2. Used-MOX-Fuel 3. Separated-Fissile 4. Separated-Waste Activity: Adding Recipes -------------------------- -We'll continue with very approximate recipes by adding a single recipe for Used-MOX-Fuel-4: +We'll continue with very approximate recipes by adding a single recipe for Used-MOX-Fuel: +------------+-----------------+ | U-235 | 0.002 | From 70ce69e712f14a72c0b0e9631c329ee21f3ffbeb Mon Sep 17 00:00:00 2001 From: Bachmann Date: Tue, 28 Oct 2025 14:24:20 -0500 Subject: [PATCH 11/26] consistent formatting in archetype names --- source/user/tutorial/add_arche_commod_recipe.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/user/tutorial/add_arche_commod_recipe.rst b/source/user/tutorial/add_arche_commod_recipe.rst index 1c5e9ae3..d8ce3ced 100644 --- a/source/user/tutorial/add_arche_commod_recipe.rst +++ b/source/user/tutorial/add_arche_commod_recipe.rst @@ -9,8 +9,8 @@ Activity: Adding Archetypes We will need two additional archetypes: -1. Add the ``cycamore FuelFab`` archetype -2. Add the ``cycamore Separations`` archetype +1. Add the ``Cycamore::FuelFab`` archetype +2. Add the ``Cycamore::Separations`` archetype Activity: Adding Commodities ----------------------------- From 208ac71e4fd23f3bf1a2736ff06c6a9c2524ad29 Mon Sep 17 00:00:00 2001 From: Bachmann Date: Tue, 28 Oct 2025 14:33:06 -0500 Subject: [PATCH 12/26] improve consistency in inputs/formatting --- .../user/tutorial/add_arche_commod_recipe.rst | 8 +++---- source/user/tutorial/add_sep.rst | 23 ++++++++++--------- 2 files changed, 16 insertions(+), 15 deletions(-) diff --git a/source/user/tutorial/add_arche_commod_recipe.rst b/source/user/tutorial/add_arche_commod_recipe.rst index d8ce3ced..093c928d 100644 --- a/source/user/tutorial/add_arche_commod_recipe.rst +++ b/source/user/tutorial/add_arche_commod_recipe.rst @@ -17,10 +17,10 @@ Activity: Adding Commodities We will need 4 additional commodities: -1. Fresh-MOX-Fuel -2. Used-MOX-Fuel -3. Separated-Fissile -4. Separated-Waste +1. fresh_mox +2. used_mox +3. Separated_Fissile +4. Separated_Waste Activity: Adding Recipes -------------------------- diff --git a/source/user/tutorial/add_sep.rst b/source/user/tutorial/add_sep.rst index 466751b3..2713c99e 100644 --- a/source/user/tutorial/add_sep.rst +++ b/source/user/tutorial/add_sep.rst @@ -14,28 +14,29 @@ The following is the input template for ``Cycamore::Separations`` archetype: - _______ + [string] - _______ + [double] - _______ - _______ - _______ - _______ + [double (kg)] + [double] + [string] + [double (kg)] - _______ + [string] - _______ + [double (kg)] - _______ - _______ + [nuclide] + [double] + ... @@ -69,7 +70,7 @@ Filling in the template, the input block looks like: 1.0 1.0 - 1000E+3_ + 1000E+3 80e+3 Separated_Waste 1000e+3 From 0342e4d95a6ecd1f4ebf629aead77bd191c36242 Mon Sep 17 00:00:00 2001 From: Bachmann Date: Tue, 28 Oct 2025 14:37:54 -0500 Subject: [PATCH 13/26] make formattting consistent, per #427 --- source/user/tutorial/add_fab.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/source/user/tutorial/add_fab.rst b/source/user/tutorial/add_fab.rst index 4775a696..01b48dc1 100644 --- a/source/user/tutorial/add_fab.rst +++ b/source/user/tutorial/add_fab.rst @@ -1,7 +1,7 @@ Adding a Stream Mixing Fuel Fabrication Facility ================================================== -The cycamore FuelFab archetype uses the _equivalence method_ to mix streams of +The cycamore FuelFab archetype uses the *equivalence method* to mix streams of fissile material with so-called "filler" material in an attempt to match neutronics of the requested material. More details about the archetype and the state @@ -19,17 +19,17 @@ archetype: - _______ + [string] - _______ - _______ + [string] + [double] - _______ + [string] - _______ - _______ - _______ - _______ + [double] + [string (`fission_spectrum_ave` or `thermal`)] + [string] + [double] @@ -42,11 +42,11 @@ plutonium and natural uranium into MOX fuel: * Filler stream commodity: ``u_ore`` * Filler stream recipe: ``nat_u`` * Filler stream inventory capacity: 1000 tonnes -* Fissile stream commodity: Separated_Fissile +* Fissile stream commodity: ``Separated_Fissile`` * Fissile stream inventory capacity: 5 tonnes -* Output Commodity: Fresh_MOX_Fuel +* Output Commodity: ``fresh_mox`` * Maximum Throughput: 2 tonnes/timestep -* Specturm type: "thermal" +* Specturm type: ``thermal`` Filling in the template, the input block looks like: @@ -62,7 +62,7 @@ Filling in the template, the input block looks like: Separated_Fissile 5000 thermal - Fresh_MOX_Fuel + fresh_mox 2000 From 7afe45db1397bd3cfbdbd8b34a865c6c0d0f7328 Mon Sep 17 00:00:00 2001 From: Bachmann Date: Tue, 28 Oct 2025 14:43:26 -0500 Subject: [PATCH 14/26] fix typo --- source/user/tutorial/add_fab.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/user/tutorial/add_fab.rst b/source/user/tutorial/add_fab.rst index 01b48dc1..55605b91 100644 --- a/source/user/tutorial/add_fab.rst +++ b/source/user/tutorial/add_fab.rst @@ -46,7 +46,7 @@ plutonium and natural uranium into MOX fuel: * Fissile stream inventory capacity: 5 tonnes * Output Commodity: ``fresh_mox`` * Maximum Throughput: 2 tonnes/timestep -* Specturm type: ``thermal`` +* Spectrum type: ``thermal`` Filling in the template, the input block looks like: From ea3f80354e8daa5432ea543e095d047c3e4c509a Mon Sep 17 00:00:00 2001 From: Bachmann Date: Tue, 28 Oct 2025 14:51:27 -0500 Subject: [PATCH 15/26] changes per #427, make things consistent --- source/user/tutorial/add_deploy.rst | 31 +++++++++++++++-------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/source/user/tutorial/add_deploy.rst b/source/user/tutorial/add_deploy.rst index b24f9de5..8b5a144e 100644 --- a/source/user/tutorial/add_deploy.rst +++ b/source/user/tutorial/add_deploy.rst @@ -2,8 +2,8 @@ Deploying New Facilities ========================== Often in fuel cycle analysis, transition scenarios are considered. These ask -questins like: "How does the -commissioning and decommissioning of reactors affect electrity production or +questions like: "How does the +commissioning and decommissioning of reactors affect electricity production or material transactions?". Transition analysis will require an institution that can deploy additional facilities at given time steps: the ``cycamore DeployInst`` archetype. This is the simplest institution @@ -12,7 +12,8 @@ new facilities, in which the user simply defines the times at which new agents should be deployed as copies of available prototypes. In this case, we will keep the current institutions and add another -institution that will deploy more facilities over time. +institution that will deploy more facilities over time, which can be used +to meet a growing electricity demand in a simulation. Example: DeployInst -------------------------------- @@ -66,27 +67,27 @@ We will now use this to add the institution for ``DeployInst``. where: -* prototype: Ordered list of prototypes to build +* prototypes: Ordered list of prototypes to build * build_times: Time step on which to deploy agents given in prototype list * n_build: Number of each prototype given in prototype list to build Activity: Add a New Institution -++++++++++++++++++++++++++++++++++++++++++ +-------------------------------- Using the table below and the DeployInst template above, fill out the commodities template. -+-------------+-------------+---------------------+ ++-----------------------+-------------+-----------+ | Prototype | build_times | n_build | -+=============+=============+=====================+ ++=======================+=============+===========+ | UraniumMine | 1 | 1 | -+-------------+-------------+---------------------+ ++-----------------------+-------------+-----------+ | FuelFab | 1 | 1 | -+-------------+-------------+---------------------+ ++-----------------------+-------------+-----------+ | 1178MWe BRAIDWOOD_1 | 2 | 1 | -+-------------+-------------+---------------------+ ++-----------------------+-------------+-----------+ | 1000MWe LIGHTWATER_1 | 3 | 1 | -+-------------+-------------+---------------------+ ++-----------------------+-------------+-----------+ Using the prototype facilities already created, the new institution should look like the following: @@ -121,16 +122,16 @@ look like the following: -The above institution will create 1 ``UraniumMine`` and 1 ``FuelFab`` facility on +The above institution will deploy 1 ``UraniumMine`` and 1 ``FuelFab`` facility on time step 1. The next time step will deploy the ``1178MWe BRAIDWOOD_1`` reactor prototype. And finally, at time step 3, the ``1000We LIGHTWATER_1`` will be deployed. This institution block goes inside the Region block, with the previously created -insitutions blocks. +institution blocks. -**ExampleInstitution** is a placeholder for your institution name, and in this scenario +``ExampleInstitution`` is a placeholder for your institution name, and in this scenario only one of each prototype will be deployed since ``n_build`` has a value of 1 for each. This example is now complete. Save your file as the desired file name (with ``.xml`` extension) and run your code through |Cyclus|. If your simulation runs into errors, sample files can be found `here `_ under -``input_deployinst.xml`` or ``ouput_deployinst.sqlite``. +``input_deployinst.xml`` or ``output_deployinst.sqlite``. From 9fb480cadab434190962fd51c9fcc58b82bd7334 Mon Sep 17 00:00:00 2001 From: Bachmann Date: Tue, 28 Oct 2025 14:53:10 -0500 Subject: [PATCH 16/26] remove mention of region --- source/user/tutorial/add_proto.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/user/tutorial/add_proto.rst b/source/user/tutorial/add_proto.rst index 42e43835..3e10be0d 100644 --- a/source/user/tutorial/add_proto.rst +++ b/source/user/tutorial/add_proto.rst @@ -304,8 +304,7 @@ Activity: Creating the Reactor Prototype Now let's model the reactor this fuel will go through! In this simple example, let's model a single PWR in the United States. It has a power capacity of 1178 -MWe, and there is only one of them in the region. -The template for the reactor is given below: +MWe. The template for the reactor is given below: .. code-block:: XML From 4650bce319631411524055dfe59a924fd617849e Mon Sep 17 00:00:00 2001 From: Bachmann Date: Tue, 28 Oct 2025 14:53:40 -0500 Subject: [PATCH 17/26] correct institution name --- source/user/tutorial/add_second_reactor.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/source/user/tutorial/add_second_reactor.rst b/source/user/tutorial/add_second_reactor.rst index 2e0f08cf..7b993f69 100644 --- a/source/user/tutorial/add_second_reactor.rst +++ b/source/user/tutorial/add_second_reactor.rst @@ -67,12 +67,12 @@ Once complete, your reactor prototype should look like: -Append this prototype right after the ``1178MWe BRAIDWOOD_1`` prototype. +Append this prototype right after the ``1178MWe BRAIDWOOD_1`` prototype in your input file. Activity: Second reactor Institution ++++++++++++++++++++++++++++++++++++ -We must add this second reactor into the region and facility section of +We must add this second reactor into the region and institution section of our |Cyclus| input file. To do so, go to the ``entry`` header under the ``initialfacilitylist`` section of the region block of the input file and add @@ -84,7 +84,7 @@ and add 1 -below the ``1178MWe BRAIDWOOD_1`` entry block. The Reactor section +below the ``1178MWe BRAIDWOOD_1`` entry block. The second institution section of the region block should now look like, .. code-block:: xml @@ -94,6 +94,8 @@ of the region block should now look like, + + @@ -111,7 +113,7 @@ of the region block should now look like, - + Note: the blank space between ```` and ```` is From abff19854a00fd4f43413bf4e913f7ed5f522e31 Mon Sep 17 00:00:00 2001 From: abachmann Date: Tue, 28 Oct 2025 15:36:16 -0500 Subject: [PATCH 18/26] adjust text for second problem --- source/user/tutorial/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/user/tutorial/index.rst b/source/user/tutorial/index.rst index c83d0f6f..f46cf538 100644 --- a/source/user/tutorial/index.rst +++ b/source/user/tutorial/index.rst @@ -35,7 +35,7 @@ Exercise #1 Exercise #2 ------------- -The description of this exercise will be described with less detail and more +The steps of this exercise will be described with less detail and more flexibility than the previous exercise. This should allow you to test your new-found knowledge, learn to explore your own analysis, and try some things on your own, all with the support of the Cyclus development team. From e560a4e3b5b61e5615a24632d04a9e26e98a465b Mon Sep 17 00:00:00 2001 From: abachmann Date: Wed, 19 Nov 2025 12:19:50 -0600 Subject: [PATCH 19/26] remove mention of institutions and regions --- source/user/tutorial/add_commod_recipe.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/user/tutorial/add_commod_recipe.rst b/source/user/tutorial/add_commod_recipe.rst index 08d016f0..0a4eac65 100644 --- a/source/user/tutorial/add_commod_recipe.rst +++ b/source/user/tutorial/add_commod_recipe.rst @@ -27,8 +27,7 @@ with the notion of mutual requests (one request that can be met through multiple commodities), complex instances of supply and demand are enabled. -Finally, requesting facilities, institutions and -regions may apply **preferences** to each potential request-bid pairing +Finally, requesting facilities may apply **preferences** to each potential request-bid pairing based on the proposed resource transfer. Facilities can apply arbitrary complex logic to **rank the bids** that they have received, whether based on the quantity available in each bid or on the quality of each bid, and From c8c389db859ad052c80f14e949bf1004f06799ec Mon Sep 17 00:00:00 2001 From: abachmann Date: Wed, 19 Nov 2025 12:25:50 -0600 Subject: [PATCH 20/26] change Archetype variable to Source in definition exercise --- source/user/tutorial/add_proto.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/user/tutorial/add_proto.rst b/source/user/tutorial/add_proto.rst index 3e10be0d..b1fc4dd5 100644 --- a/source/user/tutorial/add_proto.rst +++ b/source/user/tutorial/add_proto.rst @@ -43,7 +43,9 @@ Optional parameters: ``outrecipe``: Name of the isotopic composition of the material that this source provides - regardless of the requested composition. If empty, the Source creates and + regardless of the requested composition. If provided, + the name must match the name of a defined recipe in the + simulation. If empty, the Source creates and provides whatever composition is requested. .. code-block:: XML @@ -79,8 +81,6 @@ Archetype and the table below, create the UraniumMine prototype. +=======================+===========================+ | ``name`` | ``UraniumMine`` | +-----------------------+---------------------------+ -| ``Archetype`` | ``Source`` | -+-----------------------+---------------------------+ | ``out_commodity | ``u_ore`` | +-----------------------+---------------------------+ @@ -91,9 +91,9 @@ Archetype and the table below, create the UraniumMine prototype. name - + out_commodity - + From 37f678d03bbed9b4a3b8c72506dfbf82c45ab3f8 Mon Sep 17 00:00:00 2001 From: abachmann Date: Wed, 19 Nov 2025 12:37:02 -0600 Subject: [PATCH 21/26] ange reg/inst names, clarify region block format --- source/user/tutorial/add_reg_inst.rst | 42 ++++++++++++++++++++------- 1 file changed, 31 insertions(+), 11 deletions(-) diff --git a/source/user/tutorial/add_reg_inst.rst b/source/user/tutorial/add_reg_inst.rst index ed7601c0..4aaa76ae 100644 --- a/source/user/tutorial/add_reg_inst.rst +++ b/source/user/tutorial/add_reg_inst.rst @@ -110,17 +110,19 @@ results in the full archetype block: Concept: Regions ---------------- -Regions tie together a fuel cycle as they designate what facilities are +Regions tie together a fuel cycle as they designate what institutions and facilities are in the region's fuel cycle. Regions may apply preferences to each potential request-bid pairing based on the proposed resource transfer. -The basic structure of the ``NullRegion`` is: +The basic structure of a region block is: .. code-block:: XML Region_name - + + ... + ... @@ -133,10 +135,28 @@ Where: * ``name``: name of the region * ``config``: Region archetype to use +* ``RegionArchetype``: name of the Region archetype you wish to use in your simulation, and the dotted line in this section represents any inputs that the archetype might have. + In between the two dotted lines is where the institution and facility information goes. +In this example, we will use the ``NullRegion`` archetype, which does not have any inputs. Filling this into our region block template, we get: + +.. code-block:: XML + + + Region_name + + + + + ... + ... + + + + Concept: Institutions ----------------------------------------------------------------------- In |Cyclus| input files, each institution controls the deployment of @@ -339,8 +359,8 @@ Save your input file as ``cyclus_intro_file.xml`` Activity: Add an extra institution into the Region ------------------------------------------------- Having multiple institutions help organize facilities and their affiliation. -In our ``USA`` region, let's add a second institution called ``Exelon``. -``Exelon`` is the institution that holds the ``1178MWe BRAIDWOOD_1`` prototype and ``United +In our ``USA`` region, let's add a second institution called ``ReactorUtility``. +``ReactorUtility`` is the institution that holds the ``1178MWe ReactorPlant Unit 1`` prototype and ``United States Nuclear`` holds the ``UraniumMine``, ``EnrichmentPlant``, and ``NuclearRepository`` prototypes. @@ -348,18 +368,18 @@ prototypes. Using the template above and the table below, let's build the region. -1. Let's build the ``Exelon`` institution. This institution has one ``1178MWe BRAIDWOOD_1`` prototype. Using this information we can write this institution as: +1. Let's build the ``ReactorUtility`` institution. This institution has one ``1178MWe ReactorPlant Unit 1`` prototype. Using this information we can write this institution as: .. code-block:: XML - 1178MWe BRAIDWOOD_1 + 1178MWe ReactorPlant Unit 1 1 - Exelon + ReactorUtility @@ -400,7 +420,7 @@ Using the template above and the table below, let's build the region. -3. We will add the ``Exelon`` institution into the blank lines of our ``USA`` region +3. We will add the ``ReactorUtility`` institution into the blank lines of our ``USA`` region block. Once complete, your region prototype should look like: .. code-block:: XML @@ -434,11 +454,11 @@ Using the template above and the table below, let's build the region. - 1178MWe BRAIDWOOD_1 + 1178MWe ReactorPlant Unit 1 1 - Exelon + ReactorUtility From 0f40c3d08319f0e1aaac974bd1ce2f7dcc8a510f Mon Sep 17 00:00:00 2001 From: abachmann Date: Wed, 19 Nov 2025 15:36:07 -0600 Subject: [PATCH 22/26] edit time step duration discussion --- source/user/tutorial/sim_parm.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/source/user/tutorial/sim_parm.rst b/source/user/tutorial/sim_parm.rst index 50326b92..3f78cdd8 100644 --- a/source/user/tutorial/sim_parm.rst +++ b/source/user/tutorial/sim_parm.rst @@ -61,7 +61,6 @@ likely to be added in a future release: - 'never', all decay is turned off - 'manual', meaning it is only on if the individual archetype decays their own inventory - 'lazy', which will compute decay only when archetypes fetch a particular composition. - - 'periodic' (future), automatically decays all materials in a simulation with some fixed frequency. There are other `optional parameters `_ that could be given but are not in the scope of this tutorial. For simplicity, @@ -79,12 +78,11 @@ taken by each agent at each point in time. Each time step includes * each agent acts after the exchange of material * agents may leave the system (decommissioning) -The length of a time step is not inherently defined in |Cyclus|, the kernel works +The default time step in |Cyclus| and in this tutorial is 1 month (1/12th of a year). However, the kernel works on just the notion of a time step. There is the optional `dt` setting in the `control block `_, in which a user can set the number of seconds in a time step, which affects the -decay of materials. This tutorial assumes a time step of 1 month, which is the -default value for the `dt` input. +decay of materials. Activity: Set Simulation Parameters From 9c5e41bc3d54279247495b0a83b95dcbe06d1051 Mon Sep 17 00:00:00 2001 From: Amanda Bachmann Date: Wed, 19 Nov 2025 15:37:59 -0600 Subject: [PATCH 23/26] Apply suggestions from @gonuke code review Co-authored-by: Paul Wilson --- source/user/tutorial/add_proto.rst | 2 +- source/user/tutorial/add_reg_inst.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/user/tutorial/add_proto.rst b/source/user/tutorial/add_proto.rst index b1fc4dd5..abe18156 100644 --- a/source/user/tutorial/add_proto.rst +++ b/source/user/tutorial/add_proto.rst @@ -22,7 +22,7 @@ It offers its material as a single commodity. If a composition recipe is specified, it provides that single material composition to requesters. If unspecified, the source provides materials with the exact requested compositions. The inventory size and throughput both default to infinite. Supplying material -from the Source prototype +from an instance of a Source prototype that is deployed in a simulation results in a corresponding decrease in inventory, and when the inventory size reaches zero, the source can provide no more material. diff --git a/source/user/tutorial/add_reg_inst.rst b/source/user/tutorial/add_reg_inst.rst index 4aaa76ae..bce2e0b0 100644 --- a/source/user/tutorial/add_reg_inst.rst +++ b/source/user/tutorial/add_reg_inst.rst @@ -9,7 +9,7 @@ Institution agents that exist within a Region agent. This series of ownership allow for control of the interaction behavior between agents. For example, two facilities may not be allowed to trade if they are in two different regions. For commodities, -an institution can apply a higher preference for transactions within the +an institution may apply a higher preference for transactions within the same institution; similarly, a region may negate any transfers of material which have a higher uranium enrichment than is allowable. From 7f2348bc16176d22ecc38be04bdf0fb04d83ac94 Mon Sep 17 00:00:00 2001 From: abachmann Date: Thu, 20 Nov 2025 06:59:58 -0600 Subject: [PATCH 24/26] change minor to no consequence for archetype order --- source/user/tutorial/add_arche.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/user/tutorial/add_arche.rst b/source/user/tutorial/add_arche.rst index 164a33b3..69f56551 100644 --- a/source/user/tutorial/add_arche.rst +++ b/source/user/tutorial/add_arche.rst @@ -210,7 +210,7 @@ Once complete, your ``archetypes`` block should look like: -The order of the archetypes in this block is of minor consequence. Once complete, append the archetypes section under the control section of input file [#f1]_. +The order of the archetypes in this block is of no consequence. Once complete, append the archetypes section under the control section of input file [#f1]_. .. rubric:: Footnotes From 42723b0cca95b1a2f7dfa5979abee834922fc7fb Mon Sep 17 00:00:00 2001 From: abachmann Date: Mon, 24 Nov 2025 13:23:22 -0600 Subject: [PATCH 25/26] clarify RegionArchetype, per @dean-krueger comment --- source/user/tutorial/add_reg_inst.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/user/tutorial/add_reg_inst.rst b/source/user/tutorial/add_reg_inst.rst index bce2e0b0..31d9dd03 100644 --- a/source/user/tutorial/add_reg_inst.rst +++ b/source/user/tutorial/add_reg_inst.rst @@ -135,7 +135,7 @@ Where: * ``name``: name of the region * ``config``: Region archetype to use -* ``RegionArchetype``: name of the Region archetype you wish to use in your simulation, and the dotted line in this section represents any inputs that the archetype might have. +* ``RegionArchetype``: name of the Region archetype you wish to use in your simulation, and the dotted line in this section represents any inputs that the archetype might have. ``RegionArchetype`` is not a valid region archetype name, so that will need to change to the name of whatever region archetype you want to use. In between the two dotted lines From b94a433197239afbc599256d74a60d893eb50d03 Mon Sep 17 00:00:00 2001 From: abachmann Date: Mon, 24 Nov 2025 13:45:00 -0600 Subject: [PATCH 26/26] add section about common inputs, note about recipe names --- source/user/tutorial/add_proto.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/source/user/tutorial/add_proto.rst b/source/user/tutorial/add_proto.rst index abe18156..1866be03 100644 --- a/source/user/tutorial/add_proto.rst +++ b/source/user/tutorial/add_proto.rst @@ -10,10 +10,20 @@ reactor parameters are fuel loading parameters such as cycle length and batch size. In |Cyclus|, when an archetype has been configured with a -specific set of parameters, it is called a `**prototype** `_. You can have multiple prototypes that use the same +specific set of parameters, it is called a `prototype `_. You can have multiple prototypes that use the same archetype, and you can have multiple deployments of the same prototype in a simulation. +Each archetype will have different input parameters that need to be defined +for a given prototype, with some of the parameters being optional (i.e., they +have a default value). Some common input parameters for defining prototypes +include: + +* input/output commodity name: Name of the `commodity `_ that the prototype will request (input) or trade away (output). +* input/output recipe name: Name of the **recipe** or isotopic composition for the input or output commodity. Recipe names used in defining a prototype must be defined in a `recipe block `_ of the input file. +* throughput: The rate at which the process of a facility occurs. Common units are kg/time step, although you should check the archetypes documentation +* buffer size: The size (typically in kg) of an inventory within a prototype. A prototype may have multiple buffers, such as a reactor having an inventory for fresh fuel and one for fuel in the core. + Example: Source Prototype +++++++++++++++++++++++++ The Source facility acts as a source of material with a fixed throughput (per