diff --git a/source/user/tutorial/add_arche.rst b/source/user/tutorial/add_arche.rst index 7cc0dea4..69f56551 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 no consequence. Once complete, append the archetypes section under the control section of input file [#f1]_. .. rubric:: Footnotes diff --git a/source/user/tutorial/add_arche_commod_recipe.rst b/source/user/tutorial/add_arche_commod_recipe.rst index c7b15082..093c928d 100644 --- a/source/user/tutorial/add_arche_commod_recipe.rst +++ b/source/user/tutorial/add_arche_commod_recipe.rst @@ -2,30 +2,30 @@ 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 ----------------------------- 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 -------------------------- -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 | diff --git a/source/user/tutorial/add_commod_recipe.rst b/source/user/tutorial/add_commod_recipe.rst index de72ef75..0a4eac65 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,18 +23,15 @@ 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 -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 -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 +165,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 +197,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 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``. diff --git a/source/user/tutorial/add_fab.rst b/source/user/tutorial/add_fab.rst index 4775a696..55605b91 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" +* Spectrum 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 diff --git a/source/user/tutorial/add_proto.rst b/source/user/tutorial/add_proto.rst index 6ad8b97c..1866be03 100644 --- a/source/user/tutorial/add_proto.rst +++ b/source/user/tutorial/add_proto.rst @@ -1,31 +1,28 @@ 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. + +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 +++++++++++++++++++++++++ @@ -34,8 +31,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 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. The Source archetype is of the form: @@ -46,25 +44,27 @@ 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 + 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 - [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 +73,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 +83,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. +-----------------------+---------------------------+ @@ -91,9 +91,7 @@ Archetype and the table below, create the UraniumMine prototype. +=======================+===========================+ | ``name`` | ``UraniumMine`` | +-----------------------+---------------------------+ -| ``Archetype`` | ``Source`` | -+-----------------------+---------------------------+ -| ``out_commod`` | ``u_ore`` | +| ``out_commodity | ``u_ore`` | +-----------------------+---------------------------+ 1. The template for the Source archetype is of the form: @@ -103,14 +101,14 @@ 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 +137,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 +198,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 +219,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 +261,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,62 +284,64 @@ 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 ++++++++++++++++++++++++++++++++++++++++ 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 - 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 +358,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 +420,9 @@ The Sink archetype section is of the form: - input_commodity - input_commodity + [string] + [string] + ... @@ -429,7 +430,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 +438,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 +476,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 +490,8 @@ The sink facility archetype is: - input_commodity - input_commodity + input_commodity1 + input_commodity2 diff --git a/source/user/tutorial/add_reg_inst.rst b/source/user/tutorial/add_reg_inst.rst index b6ecb870..31d9dd03 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 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. 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 @@ -106,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 a region is: +The basic structure of a region block is: .. code-block:: XML Region_name - + + ... + ... @@ -129,14 +135,32 @@ 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`` 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 is where the institution and facility information goes. -Concept: Institution +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 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: @@ -166,6 +190,7 @@ Put together, the institution block is the form: Prototype_name number_of_prototype_names + ... Inst_name @@ -173,19 +198,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 +240,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 +271,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 +303,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 +323,7 @@ Check: Complete Region block .. code-block:: XML - region1 + USA @@ -322,65 +356,36 @@ 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 ``ReactorUtility``. +``ReactorUtility`` is the institution that holds the ``1178MWe ReactorPlant Unit 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 ``ReactorUtility`` institution. This institution has one ``1178MWe ReactorPlant Unit 1`` prototype. Using this information we can write this institution as: .. code-block:: XML - - USA - - - - 1178MWe BRAIDWOOD_1 + 1178MWe ReactorPlant Unit 1 1 - Exelon + ReactorUtility -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 +397,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 ``ReactorUtility`` institution into the blank lines of our ``USA`` region + block. Once complete, your region prototype should look like: + +.. code-block:: XML + + + USA + + + @@ -422,8 +450,26 @@ Let's first build the ``Exelon`` institution. This institution has one ``1178MWe + + + + + 1178MWe ReactorPlant Unit 1 + 1 + + + ReactorUtility + + + + + +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 ------------------------------ 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 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 diff --git a/source/user/tutorial/index.rst b/source/user/tutorial/index.rst index a135cc27..f46cf538 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 --------- @@ -36,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. 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. 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 -------------------------------------- diff --git a/source/user/tutorial/sim_parm.rst b/source/user/tutorial/sim_parm.rst index 2d9b1043..3f78cdd8 100644 --- a/source/user/tutorial/sim_parm.rst +++ b/source/user/tutorial/sim_parm.rst @@ -58,19 +58,19 @@ 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. 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 +78,16 @@ 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 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. 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. +-------------------+---------------+---------------------------------+