Reducing the verbosity of the tutorial by ConnorWelch-OSU · Pull Request #444 · cyclus/cyclus.github.com

ConnorWelch-OSU · 2026-01-27T20:58:20Z

Summary of Changes

This PR address the verbosity of the tutorial identified in #442. To reduce verbosity, repeated examples of XML blocks were removed, leaving only a template for each section of an input file. Additionally, minor changes to the text around where XML blocks were removed has been edited to fit the new context that it exists in.

Design Notes

I did not remove the XML blocks that users can use to check that their input files are correct that are at the end of some pages. There is a discussion to be had on whether these are something that we want to keep or not.

Check the box if your change does not break any of the following:

API for Cyclus modules
Input files
Output tables for post processing tools

Related CEPs and Issues

Fixes #442

Associated Developers

Testing and Validation

I have read the Contributing to Cyclus guide
I have compiled and run the code locally
I have added or updated relevant tests
I have added documentation for new or changed features
This code follows the style guide
I have updated the changelog

Reviewers, please refer to the Cyclus Guide for Reviewers.

abachma2

Thanks for doing this @ConnorWelch-OSU. I think this PR accomplishes the goal of removing some verbosity from the tutorial.

In the add_arche, add_commod_recipe and sim_parm files, it looks like you took out the completed blocks for users to compare against, but kept those in add_proto and add_reg_inst. Any reason for that inconsistency? I think having the completed blocks in the tutorial before the final input file has value.

abachma2 · 2026-01-28T14:51:27Z

source/user/tutorial/sim_parm.rst

 **Note**: There are two blank lines between the end of the control section and 
 end of the simulation section. This section of the simulation block will hold 
 the rest of the simulation parameter blocks (commodities, facilities, regions, 


Do we still need this if we don't have the completed control block anymore?

My thinking in leaving it was that the template that appears earlier in the page does contain the two blank lines. It might make more sense to have it further up the page in the section that describes the different parts of the template. I can make that change if its what we want.

Please add in those sections. I think they are valuable and make things more consistent.

Thanks for the feedback. I have added them in.

I think the added completed control block is good for the beginner as this page is their first introduction to seeing completed cyclus input!

Do we think the presence of these blank lines is distracting/concerning to learners? If so, it might be best to get rid of them than to draw attention to them with this note?

From my personal experience going through the tutorial, having the blank lines was helpful for understanding that everything else in the tutorial was going to be put in between the control block and </simulation> tag

ConnorWelch-OSU · 2026-01-28T17:34:30Z

In the add_arche, add_commod_recipe and sim_parm files, it looks like you took out the completed blocks for users to compare against, but kept those in add_proto and add_reg_inst. Any reason for that inconsistency?

I agree that having completed blocks has value. My opinion is that the completed block should appear in a "Check" section at the end of each page, and that's how they are in add_proto and add_reg_inst. I can add completed blocks back to the ends of the other pages in a "Check" section, if everyone thinks that's a good idea.

abachma2

Thanks for making that change @ConnorWelch-OSU. I am approving this PR. I'll leave this open for another few days, in case anyone else wants to look at this. Feel free to ping me to merge this if you think enough time has passed and I haven't merged this yet.

meg-krieg

Most of my comments are cosmetic except for 1 typo.

I do still think the Add Region and Institution activity could be even less verbose. There are a lot of sequences of xml blocks to get to the general template... I am not sure how that reduction would look though.

meg-krieg · 2026-01-29T20:25:10Z

source/user/tutorial/add_reg_inst.rst

-
-
-  </region>
+Let's build the ``ReactorUtility`` institution. This institution has one ``1178MWe ReactorPlant Unit 1`` prototype. 


Is this redundant compared to the above lines still under Activity?

I can make changes improve the wording.

source/user/tutorial/add_reg_inst.rst

meg-krieg · 2026-01-29T20:39:46Z

source/user/tutorial/sim_parm.rst

 **Note**: There are two blank lines between the end of the control section and 
 end of the simulation section. This section of the simulation block will hold 
 the rest of the simulation parameter blocks (commodities, facilities, regions, 


I think the added completed control block is good for the beginner as this page is their first introduction to seeing completed cyclus input!

meg-krieg · 2026-01-29T20:45:07Z

source/user/tutorial/add_proto.rst

  </facility>

 .. rubric:: Footnotes
 .. [#f1] The exact order of the sections in a |Cyclus| input file are of minor consequence. The ``control`` sequence must go first, but the other sequences can go in any order that makes sense to the user. The traditional organization  of an input file is: control, archetypes, commodities, facilities,   regions/institutions, and recipes. 


Maybe this comment isn't for this PR, but is there a better home for this footnote (and the other repeats of this footnote)? Would go with the "reduce" verbosity goal of this PR.

I agree that there would be value in stating the information from the footnote early on in the tutorial, but I decided to leave it for this PR so it can be discussed as a separate issue.

I think maybe a subsection called Structure and Syntax in the sim_parm.rst or a new page before that could be good for this footnote . That could also be a place to mention that "hyphen" comment seen in the commodities section and stuff about capitalization mattering etc.

typo fix Co-authored-by: meg-krieg <kriegm@oregonstate.edu>

ConnorWelch-OSU · 2026-01-29T21:37:41Z

Thanks for your review, @meg-krieg. I made changes to add_reg_inst.rst based on your comments.

I do still think the Add Region and Institution activity could be even less verbose. There are a lot of sequences of xml blocks to get to the general template... I am not sure how that reduction would look though.

I agree that there's still room to improve the flow here, but I think the page requires some structural changes to achieve that.

gonuke

Thanks @ConnorWelch-OSU - I've got a few comments here... Look forward to your thoughts

gonuke · 2026-02-03T19:15:40Z

source/user/tutorial/sim_parm.rst

 **Note**: There are two blank lines between the end of the control section and 
 end of the simulation section. This section of the simulation block will hold 
 the rest of the simulation parameter blocks (commodities, facilities, regions, 


Do we think the presence of these blank lines is distracting/concerning to learners? If so, it might be best to get rid of them than to draw attention to them with this note?

gonuke · 2026-02-03T19:17:03Z

source/user/tutorial/add_arche.rst

should we get rid of these underscore characters while we're at it... the table below doesn't have them

Yes, that is a good idea. I will make those changes.

gonuke · 2026-02-03T19:22:43Z

source/user/tutorial/add_arche.rst

Curious... is there any confusion in the fact that the XML entry is name but we call this variable arch1?

Also, we end up with more archetypes in this table than in the template. Any thoughts on rearranging this table to be something like:

+--------------+---------------+----------------+
| archetype # | lib | name |
+--------------+---------------+----------------+
| 1 | cycamore | Enrichment |
+--------------+---------------+----------------+
| 2 | cycamore | Reactor |
+--------------+---------------+----------------+
| 3 | cycamore | Source |
+--------------+---------------+----------------+
| 4 | cycamore | Sink |
+--------------+---------------+----------------+

I think that your suggestion for rearranging the table would be more clear than the current table, but I could see the potential for confusion with the archetype # column since lib comes before arch in the template. Maybe we get rid of the lib and arch numbering in the template all together and just direct the user create four <spec> blocks with the information in the table. What are your thoughts on that?

I noticed that in later pages, we put [string] in the placeholders. Maybe that's more consistent ~~and we can then replace arch with name since name is the XML element~~.

So, for clarity, we would replace lib1, arch1, etc. in the template with [string]. But then, where is the arch that we would be replacing with name?

Right! My new table suggestion had already referred to name so you can ignore that part of my comment

gonuke · 2026-02-03T19:25:12Z

source/user/tutorial/add_commod_recipe.rst

Should we remove this section or move it somewhere else? It's an optional and advanced feature that we haven't really explained. I think we can talk about the role of commodities without describing how or the option of adding a commodities block...

Maybe my understanding is lacking, but don't wee need to define the commodities in order to use them as in and out commodities for prototypes?

We don't need to define them. Your understanding may actually stem from this part of the tutorial! 😀

Commodities are defined implicitly by their use in archetypes.

In that case, I agree. This section isn't necessary, and may even cause confusion, as it did for me. If we were to move it, where would be the best place for it? Otherwise, I can remove it.

I think the part that introduces the concept of commodities within the DRE is useful and can stay. Starting with the "Activity" we can remove it and add a sentence or two that states that commodities don't have to be explicitly defined. Rather, they are defined implicitly by the facilities and the commodities they choose to trade.

gonuke · 2026-02-03T19:26:02Z

source/user/tutorial/add_reg_inst.rst

+| ``arch6``   | ``NullInst``     | Name of archetype          |
 +-------------+------------------+----------------------------+

 .. code-block:: XML


So we need this template again, or can we just refer back to the earlier location?

We can probably exclude the template here and refer back to the archetypes page. The other option would be to instruct the user to add NullRegion and NullInst on the archetypes page.

I think we avoid putting these on the archetypes page because we haven't introduced the concept of regions and institutions yet.

That makes sense. I will remove the template here and add a reference to the archetypes page.

source/user/tutorial/add_proto.rst

ConnorWelch-OSU · 2026-02-06T00:13:18Z

Thanks for the detailed review @gonuke. I've made the following changes to address your suggestions.

In add_arche.rst, I rearranged the table to remove lib1, arch1, etc. naming, but kept the columns as Variable and Value to match the way the majority of the tables in the tutorial are. Let me know what you think of the way I formatted the table.
In add_reg_inst.rst, I removed the repeated template and replaced it with a link to the Understanding Archetypes page.
I removed the optional add commodity activity, and I'm pretty sure I tracked down and removed any references to a commodity block in the rest of the tutorial, including the input files.

I also fixed the formatting for the code block and table in add_deploy.rst that I noticed weren't rendering properly on the website while looking for commodity references.

gonuke

This is getting close, @ConnorWelch-OSU - a couple of little comments/requests here

gonuke · 2026-02-07T04:02:45Z

source/user/tutorial/add_arche.rst

+=============+=============+==================+
+| 1           | ``lib``     | ``cycamore``     |
+             +-------------+------------------+
+|             | ``arch``    | ``Source``       |


There is no variable named "arch" - can we change this to "name"?

gonuke · 2026-02-07T04:07:05Z

source/user/tutorial/add_commod_recipe.rst

      <name>nat_u</name>
      <basis>mass</basis>
      <nuclide>
        <id>92235</id>
        <comp>0.00711</comp>
      </nuclide>
      <nuclide>
        <id>92238</id>
        <comp>0.99289</comp>


Should this be a template, per our normal pattern?

gonuke · 2026-02-07T04:09:04Z

source/user/tutorial/add_reg_inst.rst

+=============+=============+==================+
+| 5           | ``lib``     | ``agents``       |
+             +-------------+------------------+
+|             | ``arch``    | ``NullRegion``   |


ConnorWelch-OSU added 6 commits January 27, 2026 11:14

remove step by step instruction in activity

b031885

remove archetype block template and check

0c12781

remove step by step instructions for commodity and recipe activities

b81e7bd

remove excess code blocks from activities

0613e54

remove extra region template and step by step for second institution

0838201

make activity instruction match context

2b1bdd8

ConnorWelch-OSU requested review from abachma2, dean-krueger, gonuke, meg-krieg and munkm January 27, 2026 20:59

abachma2 reviewed Jan 28, 2026

View reviewed changes

add missing check sections

26bba24

abachma2 approved these changes Jan 29, 2026

View reviewed changes

meg-krieg suggested changes Jan 29, 2026

View reviewed changes

ConnorWelch-OSU and others added 2 commits January 29, 2026 12:49

Update source/user/tutorial/add_reg_inst.rst

fe2e81a

typo fix Co-authored-by: meg-krieg <kriegm@oregonstate.edu>

improve wording for second inst activity

0289a21

ConnorWelch-OSU requested a review from meg-krieg January 29, 2026 21:37

gonuke requested changes Feb 3, 2026

View reviewed changes

ConnorWelch-OSU added 9 commits February 4, 2026 12:05

change archetype activity table

af59e01

add reference to add_arche in add_reg_inst

fe8b3b9

update agents archetype table

ecff641

made order of archetypes consistent

e6d25bd

remove commodity block from input files

cca9bb9

remove add commodity activity

cce6d37

remove references to commodity section

a54c5f4

fix code block and table formatting

1963945

remove commodity block references from later scenarios

cc07c94

remove commodity blocks from recap

08fbcda

ConnorWelch-OSU requested review from abachma2 and gonuke February 6, 2026 00:13

ConnorWelch-OSU added 2 commits February 5, 2026 16:17

remove commodity from check section

071aad1

fix undestanding archetypes link

c9cf153

gonuke requested changes Feb 7, 2026

View reviewed changes



		</region>
		Let's build the ``ReactorUtility`` institution. This institution has one ``1178MWe ReactorPlant Unit 1`` prototype.

	\| \| ``arch`` \| ``NullRegion`` \|
	\| \| ``name`` \| ``NullRegion`` \|

Conversation

ConnorWelch-OSU commented Jan 27, 2026

Summary of Changes

Design Notes

Related CEPs and Issues

Associated Developers

Testing and Validation

Uh oh!

abachma2 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ConnorWelch-OSU commented Jan 28, 2026

Uh oh!

abachma2 left a comment

Choose a reason for hiding this comment

Uh oh!

meg-krieg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ConnorWelch-OSU commented Jan 29, 2026

Uh oh!

gonuke left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gonuke Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gonuke Feb 4, 2026 •

edited

Loading