Improve the High-Level Introduction to ARMI in the Docs

[john-science]

Right now, ARMI technically has a high-level introduction in two places:

• REAME.rst - Covers everything from installation to core concepts
• doc/developer/guide.rst - It feels strange that this is in "developer docs" and not "user docs".

I also note that there are installation instructions in two places:

• README.rst - Quick Start
• User Docs

I don't love that. But I DO love that we are including our README file as the introduction to our docs:

armi/doc/index.rst

Line 21 in b9f1f13

.. include:: ../README.rst

Also, I don't super love the order of our docs:

armi/doc/index.rst

Lines 11 to 15 in b9f1f13

	installation
	gallery/index
	tutorials/index
	user/index
	developer/index

[john-science]

Implementation of Plugin System

The first important design idea to understand is ARMI it is a framework for nuclear reactor modeling. What this means, is that none of the science or engineering calculations for nuclear reactor modeling actually happen in ARMI. The point of ARMI is to tie together disparate nuclear modeling softwares that already exist. Thus, ARMI must be able to wrap external codes, and orchestrate running them at each time step we want to model.

The second design idea is that at each time step, there is an ordered list of conceptual reactor modeling steps to be executed. ARMI calls these steps :py:class:Interfaces <armi.interfaces.Interface> and runs the code, in order, at each time step. While ARMI does have a default list of modeling steps, and a default order, none of the steps are mandatory, and their order is modifiable. An example interface stack would be:

• preprocessing
• fuel management
• depletion
• fuel performance
• cross sections
• critical control
• flux
• thermal hydraulics
• reactivity coefficients
• transient
• bookkeeping
• postprocessing

So, how do we add Interfaces to the simulation? The third major design idea is that developers can create an ARMI :py:class:Plugin <armi.plugins.ArmiPlugin>, which can add one or more Interfaces to the simulation.

Lastly, at the highest level of the design, a developer can create an ARMI :py:class:Application <armi.apps.App>. This is a flexible container that allows developers to register multiple Plugins, which register multiple Interfaces, which fully define all the code that will be run at each time step of the simulation.

Below is a diagram from an example ARMI Application. Following this design, in the real world you would expect an ARMI Application to be made by various teams of scientists and engineers that define one Plugin and a small number of Interfaces. Then a simulation of the reactor would be carried out over some number of cycles / time nodes, where each of the Interfaces would be run in a specified order at each time node.

Figure: An example ARMI Application.

If this high-level design seems abstract, that is by design. ARMI is not concerned with implementing scientific codes, or enforcing nuclear modelers do things a certain way. ARMI is a tool that aims to support a wide audience of nuclear reactor modelers.

Implementation of Reactor Data Model

In the previous section, we described how an ARMI Application is put together. But that Application is only useful if it can pass information about the reactor between all the external codes that are being wrapped by each Interface. Thus, an important part of the ARMI design is that is has a robust and detailed software data model to represent the current state of the reactor. This data model can be queried and manipulated by each Interface to get data that is needed to run the external reactor modeling codes.

The structure of the ARMI reactor data model is designed to be quite flexible, and heavily modifiable in code. But for the purposes of Natrium, this document will focus on pin-type reactor cores.

At the largest scale, the :py:class:Reactor <armi.reactor.reactors.Reactor> contains a :py:class:Core <armi.reactor.reactors.Core> and a :py:class:Spent Fuel Pool <armi.reactor.assemblyLists.SpentFuelPool>. The Core is made primarily of a collection of :py:class:Assemblies <armi.reactor.assemblies.Assembly>, which are vertical collections of :py:class:Blocks <armi.reactor.blocks.Block>. Each Block, and every other physical piece of the Reactor is a :py:class:Composite <armi.reactor.composites.Composite>. Composites have a defined shape, material(s), location in space, and parent. Composites have parents because ARMI defines all Reactors as a hierarchical model, where outer objects contain inner children and the Reactor is the outermost object. The important thing about this model is that it is in code, so developers of ARMI Interfaces can query and modify the reactor data model in any way they need.

Figure: Structure of the ARMI reactor data model.