Advanced C++ Archetype Developer Tutorial #421

dean-krueger · 2025-07-27T17:32:39Z

Summary of Changes

A long time ago someone asked for a more advanced C++ archetype development tutorial. I read this comment and thought: "I also wanted a little more hand holding while learning how to do this", and so I combined my two favorite things: infrastructure/documentation and using AI to do things I don't want to and came up with this PR. The Advanced C++ Archetype Developer Tutorial adds 5, almost entirely AI generated (but human checked, more on this later) documentation/tutorial pages to the Cyclus website in service of bringing new Cyclus Archetype developers up to speed more quickly.

The first page it adds is a thorough overview of the DRE from the perspective of an Archetype developer, diving into the DRE's place in the Cyclus time step, the functions which need to be called to interact with the DRE (including preference adjustment!), and a few other goodies.

The second page aims to address the lack of a "more advanced" agent (read facility) tutorial for people who are interested in doing a bit more than just making a storage facility. It covers MatQuery, TimeSeries, More DRE function implementation (this is something I found to be particularly opaque when I was starting, that may just be me, though), position tracking, database interactions (see Tricycle) and a few other toolkit things.

The third, fourth and fifth pages are really the gem of this tutorial, in my opinion, and take the user through the full experience of creating a Facility (Conversion), Institution (RandomEventInst), and Region (TariffRegion) through example code in a (hopefully) very tutorialized way. The aim of these pages is to put everything learned in pages 1 and 2 together, and also to make sure that developers know they can create any type of agent, and how to do so (Cycamore is a bit lacking in examples).

Related CEPs and Issues

This PR is related to:

Closes Is there a more detailed tutorial? cyclus#1576

Associated Developers

Cursor AI (more on this later)

Design Notes

This is the section you've all been waiting for: the part where I explain my use of AI. I was recently turned on to a new AI tool called Cursor, which is basically a clone of VS code but which has an LLM incorporated. It indexes all of your files (in this case the Cyclus, Cycamore, cyclus.github.com, and Tricycle repos that I've been working on) and uses its knowledge of coding best practices and, importantly, the specific code that you present it to make tasks like this sort of documentation/tutorial making very fast and thorough.

It is worth noting that I have personally gone through each file and found (slight) mistakes in the things it came up with, but unlike previous attempts I've made at this (ChatGPT specifically) the mistakes were infrequent and small enough that I felt confident in the tools ability to get MOST things right.

THAT BEING SAID:
I have talked with @gonuke about this before and we have a constantly evolving discussion about the use of AI in our work. My goal is to be as transparent about it as possible (which is why I'm spending so much of this PR talking about its use), but think that while it certainly has pitfalls, its use for tasks like this are especially high-reward (since writing documentation is a bit of a massive chore that isn't easy to fund). This PR is an attempt to introduce this idea to the Cyclus community, get feedback on whether it's "worth it" or not, and to potentially, hopefully, do so while adding something useful to our documentation.

My request of anyone who might want to review this is to, whenever possible and to whatever extent possible, please give this a through read. I have done my best (and will continue to tweak and test and correct as this PR progresses) to catch Cursor where it was wrong, but I may have missed some things. If you see something fishy, point it out. Like I said earlier, I am confident enough in this tool (where I wasn't with others) that I'm presenting this, but correctness > ease.

Testing and Validation

I have built the website on my local machine, and from that point of view this all "works". Additionally, I have based a lot of the Conversion facility (cyclus/cycamore#657) on these tutorials, and used that as a method to vet what Cursor was saying. You will notice that there are differences between cyclus/cycamore#657 and the conversion facility in the tutorial (there were a few places where I specifically instructed Cursor to focus more on showing off features than having a nice, simple facility suitable for Cycamore).

Things I have not yet done but which I plan to do soon (ran out of time today, but wanted to get this in front of people before the week started):

Implement the full Conversion, RandomEventInst, and TariffRegion agents to make sure the code as-tutorialized works (I did read it carefully and look for obvious mistakes, though)
Fully vetted the DRE tutorial (I tested parts of it and made a few very small corrections (mostly a few "best practices" edits and not "completely wrong" ones)
Had a new cyclus agent developer run through the tutorial (@trysarahtops if you have time this might be a good way to get you some experience while helping me out, sort of a win-win). If anyone has new students who are working on development stuff who might be able to help me with this/benefit from these tutorials let me know. This is probably the best way to check things.

Checklist

Read the Contributing to Cyclus guide.
Compile and run locally.
Follow style guidelines.
Update the changelog.
Address all review comments.
Reviewers, please refer to the Cyclus Guide for Reviewers.

…l using ChatGPT

…lso made some stuff up with how the DRE works...

…to advanced-tutorial

…ry minor) errors.

dean-krueger · 2025-08-05T23:28:44Z

Update: the region tutorial code builds in Cycamore as written.

katyhuff

Thanks for creating this PR!
I haven't read every word, but I have looked over it in some detail. I have made some suggestions. Also, have you checked that if you follow these tutorials you actually get facilities/insts/etc. that work? That may be needed. Perhaps @SamarAbdelkawy would be willing to try it?

katyhuff · 2025-09-04T14:49:04Z

source/arche/tutorial_cpp/advanced_agent.rst

+In this lesson, we will:
+
+1. Master the MatQuery toolkit for material analysis
+2. Implement direct DRE functions without toolkit policies


I think it's helpful in the tutorial pages to make sure you're expanding the acronyms fairly often (e.g. on new pages) so folks don't have to go searching through other pages.

Suggested change

2. Implement direct DRE functions without toolkit policies

2. Implement direct Dynamic Resource Exchange (DRE) functions without toolkit policies

katyhuff · 2025-09-04T14:52:04Z

source/arche/tutorial_cpp/advanced_agent.rst

+Basic MatQuery Usage
++++++++++++++++++++
+
+MatQuery allows you to easily extract information from material objects:


Perhaps give a little more context for the example below.

Suggested change

MatQuery allows you to easily extract information from material objects:

MatQuery allows you to easily extract information from material objects.

Below is a dummy example of a function that leverages a few of the capabilities

in the MatQuery toolkit. You can use these capabilities within the functions and

methods in your custom facility by including the MatQuery toolkit as is done at the

top of this example:

katyhuff · 2025-09-04T14:54:18Z

source/arche/tutorial_cpp/advanced_agent.rst

+    void MyFacility::AdjustMatlPrefs(PrefMap<Material>::type& prefs) {
+      PrefMap<Material>::type::iterator pmit;
+      for (pmit = prefs.begin(); pmit != prefs.end(); ++pmit) {
+        Request<Material>* req = pmit->first;
+
+        // Adjust preferences based on bid characteristics
+        for (mit = pmit->second.begin(); mit != pmit->second.end(); ++mit) {
+          Bid<Material>* bid = mit->first;
+          Material::Ptr offer = bid->offer();
+
+          // Prefer material with higher U-235 content
+          cyclus::toolkit::MatQuery mq(offer);
+          double u235_frac = mq.atom_frac(922350000);
+          mit->second = mit->second + u235_frac * 100;
+
+          // Penalize material from certain facility types
+          if (dynamic_cast<Reactor*>(bid->bidder()) != NULL) {
+            mit->second = mit->second - 50;  // Prefer fresh fuel
+          }
+        }
+      }
+    }


Have you checked that blocks like this compile and run properly?

katyhuff · 2025-09-04T14:55:43Z

source/arche/tutorial_cpp/advanced_agent.rst

+.. code-block:: c++
+
+    #include "toolkit/symb_func.h"
+
+    void MyFacility::SetupCostFunction() {
+      // Create a cost function based on throughput
+      cyclus::toolkit::SymbFunctionFactory factory;
+
+      // Cost = base_cost + throughput * variable_cost
+      std::string expr = "base_cost + throughput * variable_cost";
+      cost_function_ = factory.Create(expr);
+
+      // Set parameters
+      cost_function_->SetVariable("base_cost", 1000.0);
+      cost_function_->SetVariable("variable_cost", 50.0);
+    }
+
+    double MyFacility::CalculateCost(double throughput) {
+      cost_function_->SetVariable("throughput", throughput);
+      return cost_function_->Eval();
+    }


I didn't realize we had this!

katyhuff · 2025-09-04T14:57:26Z

source/arche/tutorial_cpp/creating_conversion.rst

+a Conversion Facility. This guide is designed for beginners—especially new
+Cyclus users—who are just starting with Cyclus and C++ agent


The em-dashes are a little jarring here.

Suggested change

a Conversion Facility. This guide is designed for beginners—especially new

Cyclus users—who are just starting with Cyclus and C++ agent

a Conversion Facility. This guide is designed for beginners, especially new

Cyclus users who are just starting with Cyclus and C++ agent

katyhuff · 2025-09-04T15:07:10Z

source/arche/tutorial_cpp/custominst.rst

+Creating a Custom Institution
+=============================
+
+This chapter walks through the creation of a **custom Cyclus Institution archetype**, illustrating how institutions can coordinate deployment, set policy, or aggregate data across child agents.


Consider hardwrapping this line at 80 chars.

katyhuff · 2025-09-04T15:07:18Z

source/arche/tutorial_cpp/custominst.rst

+
+---
+
+A Cyclus Institution is an agent that owns and manages a set of child facilities. It does **not** directly interact with the DRE unless explicitly programmed to do so.


Consider hardwrapping this line at 80 chars.

katyhuff · 2025-09-04T15:07:22Z

source/arche/tutorial_cpp/custominst.rst

+
+---
+
+Let’s define a new Institution called `SmartDeployInst`. This agent dynamically deploys a set of child facilities according to a time-series demand signal and manages their geographic position metadata.


Consider hardwrapping this line at 80 chars.

katyhuff · 2025-09-04T15:07:28Z

source/arche/tutorial_cpp/custominst.rst

+* Control dynamic deployment of facilities
+* Support geographically or economically nuanced behaviors
+
+You now have all the tools necessary to design complex institutional agents that implement scenario logic, enforce system-wide policy, and guide the evolution of your simulation.


Consider hardwrapping this line at 80 chars.

katyhuff · 2025-09-04T15:07:30Z

source/arche/tutorial_cpp/custominst.rst

+
+---
+
+Custom institutions are powerful coordination points in Cyclus simulations. By extending basic `Tick()` logic and using toolkit helpers, your institution can:


Consider hardwrapping this line at 80 chars.

abachma2

Thanks for working on this @dean-krueger. A few general thoughts:

To me, a tutorial should follow a story line, and I think some of these pages do. But there are a few that seem more like information dumps.
There is some overlap with existing pages.
You might want to consider some re-ordering or moving content around within the source/arche directory to have a fluid story in the tutorials and have valuable information in other pages.

abachma2 · 2025-09-08T16:38:57Z

source/arche/tutorial_cpp/advanced_agent.rst

+Direct DRE Implementation
+------------------------
+
+While the toolkit provides convenient buy/sell policies, sometimes you need
+more control over the DRE process. Here's how to implement DRE functions
+directly without using toolkit policies.


2 things:

This section feels like it overlaps with what is in source/arche/dre.rst. -- maybe have a pointer to this page instead in the tutorial for if a developer wants to do this

Going through the current c++ tutorial, is this what the MatBuyPolicy and MatSellPolicy lines do for a user? I'm not familiar with those functions so I haven't ever used them.

abachma2 · 2025-09-08T16:44:07Z

source/arche/tutorial_cpp/advanced_agent.rst

+        cyclus::toolkit::RecordTimeSeries<cyclus::toolkit::POWER>(this, power_output);
+        cyclus::toolkit::RecordTimeSeries<double>("supplyPOWER", this, power_output);


Is there a reason both lines are used here? I see that they create 2 different tables in the output database, but do we need both tables?

abachma2 · 2025-09-08T16:44:58Z

source/arche/tutorial_cpp/advanced_agent.rst

+Custom Time Series
+++++++++++++++++
+


Does this add anything new from the previous section for time series recording?

abachma2 · 2025-09-08T16:51:09Z

source/arche/tutorial_cpp/advanced_agent.rst

+Adding Position to Archetypes
++++++++++++++++++++++++++++
+
+Include the position snippet in your archetype header:


Suggested change

Include the position snippet in your archetype header:

Include the position snippet in your archetype header (`myfacility.h`:

Just to make things clear/easy for the reader

abachma2 · 2025-09-08T16:51:26Z

source/arche/tutorial_cpp/advanced_agent.rst

+Initializing Position
++++++++++++++++++++
+
+Initialize the position in your ``EnterNotify()`` method:


Suggested change

Initialize the position in your ``EnterNotify()`` method:

Initialize the position in your ``EnterNotify()`` method of your archetype file (`myfacility.cc`):

abachma2 · 2025-09-08T20:48:35Z

source/arche/tutorial_cpp/creating_tariff_region.rst

+Creating TariffRegion
+====================
+
+In this tutorial, you will learn how to build a Cyclus Region Agent that


Agent or archetype?

abachma2 · 2025-09-08T20:52:10Z

source/arche/tutorial_cpp/creating_tariff_region.rst

+File Structure: .h vs .cc
+-------------------------
+


Same note about having this information in a central location.

abachma2 · 2025-09-08T20:53:58Z

source/arche/tutorial_cpp/creating_tariff_region.rst

+Conclusion
+----------


Just now thinking of this: Do we want to have something about building the files? Earlier parts of the tutorial touch on this, like rebuilding as you make edits.

abachma2 · 2025-09-08T20:55:03Z

source/arche/tutorial_cpp/custominst.rst

+
+.. code-block:: cpp
+
+\#ifndef SMART\_DEPLOY\_INST\_H\_


What is with the \ throughout this line and the next few?

abachma2 · 2025-09-08T20:56:29Z

source/arche/tutorial_cpp/dre_overview.rst

This file seems like a repeat of source/arche/dre.rst. Is there a reason you added the material here?

dean-krueger added 5 commits June 16, 2025 15:55

Addded the foundation of an advanced Cyclus Agent development tutoria…

8057a14

…l using ChatGPT

started working out the formatting errors Chat had. Noticed that it a…

d5bb84d

…lso made some stuff up with how the DRE works...

Merge branch 'source' of github.com:dean-krueger/cyclus.github.com in…

3121e4d

…to advanced-tutorial

removed old tutorial files and added some new (better) ones

2ec1a81

added more to advanced tutorial, did some checking and found some (ve…

4b6e60b

…ry minor) errors.

dean-krueger requested review from katyhuff, gonuke, munkm, nuclearkatie, abachma2, nsryan2, GersonEsquivel and trysarahtops July 27, 2025 17:32

dean-krueger self-assigned this Jul 27, 2025

katyhuff requested changes Sep 4, 2025

View reviewed changes

abachma2 requested changes Sep 8, 2025

View reviewed changes

	2. Implement direct DRE functions without toolkit policies
	2. Implement direct Dynamic Resource Exchange (DRE) functions without toolkit policies

-MatQuery allows you to easily extract information from material objects:
+MatQuery allows you to easily extract information from material objects.
+Below is a dummy example of a function that leverages a few of the capabilities
+in the MatQuery toolkit. You can use these capabilities within the functions and
+methods in your custom facility by including the MatQuery toolkit as is done at the
+top of this example:

		a Conversion Facility. This guide is designed for beginners—especially new
		Cyclus users—who are just starting with Cyclus and C++ agent


		---

		A Cyclus Institution is an agent that owns and manages a set of child facilities. It does not directly interact with the DRE unless explicitly programmed to do so.


		---

		Let’s define a new Institution called `SmartDeployInst`. This agent dynamically deploys a set of child facilities according to a time-series demand signal and manages their geographic position metadata.


		---

		Custom institutions are powerful coordination points in Cyclus simulations. By extending basic `Tick()` logic and using toolkit helpers, your institution can:

		cyclus::toolkit::RecordTimeSeries<cyclus::toolkit::POWER>(this, power_output);
		cyclus::toolkit::RecordTimeSeries<double>("supplyPOWER", this, power_output);

	Include the position snippet in your archetype header:
	Include the position snippet in your archetype header (`myfacility.h`:

	Initialize the position in your ``EnterNotify()`` method:
	Initialize the position in your ``EnterNotify()`` method of your archetype file (`myfacility.cc`):

		File Structure: .h vs .cc
		-------------------------

		Conclusion
		----------

Advanced C++ Archetype Developer Tutorial #421

Are you sure you want to change the base?

Advanced C++ Archetype Developer Tutorial #421

Uh oh!

Conversation

dean-krueger commented Jul 27, 2025

Summary of Changes

Related CEPs and Issues

Associated Developers

Design Notes

Testing and Validation

Checklist

Uh oh!

dean-krueger commented Aug 5, 2025

Uh oh!

katyhuff 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!

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!

abachma2 left a comment

Choose a reason for hiding this comment

Uh oh!

abachma2 Sep 8, 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!

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!

Uh oh!

abachma2 Sep 8, 2025 •

edited

Loading