Tutorial Updates #433

abachma2 · 2025-10-28T20:40:15Z

Summary of Changes

This PR addresses some of the items identified by me in #427 to update the user tutorial. The changes are generally pretty minor: fixing typos, correcting formats, making things consistent across the tutorial. Some of the wording changes improve the clarity of the tutorial for me and I welcome discussion if you think the changes make things less clear.

Design Notes

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

This PR addresses some of the items in #427, but not all of them so the issue should remain open after merging.

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.

gonuke · 2025-10-29T18:50:55Z

See also #426

abachma2 · 2025-10-29T21:43:31Z

See also #426

I will add that to the Tutorial update project. I don't want to do that update with this PR to maintain some formal scope. I can get another PR in to address that issue.

gonuke

Thanks for this careful review @abachma2 . I have reviewed all your changes, but haven't done a full read to confirm that the changes are any more/less consistent with the tutorial - I'll trust you on that. There are a few places where I did look at the context of the changes and asked some questions.

gonuke · 2025-11-14T17:44:23Z

source/user/tutorial/add_arche.rst

    </archetypes>

-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]_.


I'm not sure I know what "minor consequence" means.... does the order matter at all?

As far as I know, the only ordering that matters in a Cyclus input file is that the control block needs to go first. I don't know if there are any other things that matter. I can change minor to no if that is more accurate.

I think "no consequence" would be better

Forgot to save that with my last round of edits. It is now changed.

source/user/tutorial/sim_parm.rst

source/user/tutorial/add_commod_recipe.rst

source/user/tutorial/add_proto.rst

source/user/tutorial/add_reg_inst.rst

gonuke · 2025-11-14T18:09:11Z

source/user/tutorial/add_reg_inst.rst

+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. 


We don't have ... in this example. I think we need to add that for this to make sense

I did add that in. Line 193.

source/user/tutorial/add_reg_inst.rst

gonuke · 2025-11-14T18:14:46Z

source/user/tutorial/add_sep.rst

                 <item>
-                   <comp>_______</comp>
-                   <eff>_______</eff>
+                   <comp>[nuclide]</comp>


I think this needs to refer to an element??? or is that just a convention. Separations acts on elements not isotopes...

Elsewhere on the website I see that we have nuclide: https://fuelcycle.org/user/cycamoreagents.html#cycamore-separations. I don't actually know that answer.

Co-authored-by: Paul Wilson <paul.wilson@wisc.edu>

gonuke

I have one minor comment and then ready to approve these.

That said, we had a discussion in my group meeting today about the high level design of the tutorials and may want to discuss that on the next Cyclus call, if not sooner.

gonuke · 2025-11-20T22:30:54Z

source/user/tutorial/add_proto.rst

    <config>
-      <Archetype>
-        <outcommod>outcommod</outcommod>
+      <Source>


In all the other places that we describe "templates" we leave these as <Archetype> and then replace it later.

This has led to a different conversation about how verbose these tutorials are where we often:

give an example

give the template

give the filled in template that is often the same as the example

I don't expect this PR to fix that, but we should discuss the overall flow of the tutorials some time.

dean-krueger · 2025-11-22T13:59:27Z

source/user/tutorial/add_reg_inst.rst

+* ``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.
+


Perhaps a note that RegionArchetype isn't (currently, at least) a valid input in this block and that it must be replaced with the actual region name with an example like <NullRegion>. What you have implies this, but users new to Cyclus/XML may get tripped up by this.

dean-krueger · 2025-11-22T14:06:52Z

source/user/tutorial/add_second_reactor.rst

  </facility>

-Append this prototype right after the ``1178MWe BRAIDWOOD_1`` prototype.
+Append this prototype right after the ``1178MWe BRAIDWOOD_1`` prototype in your input file.


I think in the last tutorial you changed 1178MWe BRAIDWOOD_1 to 1178MWe ReactorPlant Unit 1

dean-krueger · 2025-11-22T14:07:25Z

source/user/tutorial/add_second_reactor.rst

  </entry>

-below the ``1178MWe BRAIDWOOD_1`` entry block. The Reactor section
+below the ``1178MWe BRAIDWOOD_1`` entry block. The second institution section


See above about 1178MWe ReactorPlant Unit 1 vs BRAIDWOOD

dean-krueger

Awesome work, this is a lot better for having been gone through like you did. I left two or three comments separately, but they're all pretty minor. Otherwise looks good to me!

abachma2 added 18 commits October 27, 2025 16:18

remove mention of internet connection

7a3844e

consolidate Cyclus and Cycamore to single link

19ad825

make edits suggested in cyclus#427

e01ca79

make minor revisions, per cyclus#427

ce47b36

minor revisions, per cyclus#427

5eac5ec

make formatting more consistent

5f3289c

changes, per cyclus#427, includes some reordering

0481e5f

remove cloud paragraph, add terminal running

b0e0aaf

add note about insts deploying prototypes

7d653d9

changes per cyclus#427

7e891e5

consistent formatting in archetype names

70ce69e

improve consistency in inputs/formatting

208ac71

make formattting consistent, per cyclus#427

0342e4d

fix typo

7afe45d

changes per cyclus#427, make things consistent

ea3f803

remove mention of region

9fb480c

correct institution name

4650bce

adjust text for second problem

abff198

abachma2 requested review from GersonEsquivel, RhysMacMillan, SamarAbdelkawy, dean-krueger, gonuke and katyhuff October 28, 2025 20:40

abachma2 self-assigned this Oct 28, 2025

abachma2 added this to 2025 Tutorial Update Oct 28, 2025

gonuke requested changes Nov 14, 2025

View reviewed changes

remove mention of institutions and regions

e560a4e

abachma2 and others added 4 commits November 19, 2025 12:25

change Archetype variable to Source in definition exercise

c8c389d

ange reg/inst names, clarify region block format

37f678d

edit time step duration discussion

0f40c3d

Apply suggestions from @gonuke code review

9c5e41b

Co-authored-by: Paul Wilson <paul.wilson@wisc.edu>

abachma2 mentioned this pull request Nov 19, 2025

[Feature] Need to define mutual requests on the website. #434

Open

change minor to no consequence for archetype order

7f2348b

gonuke requested changes Nov 20, 2025

View reviewed changes

dean-krueger reviewed Nov 22, 2025

View reviewed changes

dean-krueger requested changes Nov 22, 2025

View reviewed changes

		* ``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.

Tutorial Updates #433

Are you sure you want to change the base?

Tutorial Updates #433

Uh oh!

Conversation

abachma2 commented Oct 28, 2025

Summary of Changes

Design Notes

Related CEPs and Issues

Associated Developers

Testing and Validation

Uh oh!

gonuke commented Oct 29, 2025

Uh oh!

abachma2 commented Oct 29, 2025

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gonuke left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dean-krueger Nov 22, 2025 • 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!

dean-krueger left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dean-krueger Nov 22, 2025 •

edited

Loading