Advanced C++ Archetype Developer Tutorial

[dean-krueger]

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.

[dean-krueger]

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