1. Software Requirements Specification Document (SRSD)

1.1. Purpose

This Software Requirements Specification Document (SRSD) is prepared for the Advanced Reactor Modeling Interface (ARMI) framework. The purpose of thisdocument is to define the functional requirements, I/O requirements, relevant attributes, and applicable design constraints for ARMI.

This SRSD will be accompanied by a Software Design and Implementation Document (SDID), that describes how the requirements are implemented within the software and a Software Test Report (STR), that documents the test plan and reporting of test results.

1.2. Introduction

The Advanced Reactor Modeling Interface (ARMI®) is an open-source framework for nuclear reactor design and analysis. Based on Python, ARMI provides a richly-featured toolset for connecting disparate nuclear reactor modeling tools. ARMI is not meant to directly implement the science or engineering aspects of nuclear reactor modeling, but to help the wealth of existing models work together. It does this by providing easy-to-use tools for coordinating reactor simulation and analysis workflows. A large part of the power of ARMI is that it provides a flexible in-memory data model of a reactor, which is used to pass information between different external tools.

ARMI:

• Provides a hub-and-spoke mechanism to standardize communication and coupling between physics kernels and the specialist analysts who use them,

• Facilitates the creation and execution of detailed models and complex analysis methodologies,

• Provides an ecosystem within which to rapidly and collaboratively build new analysis and physics simulation capabilities, and

• Provides useful utilities to assist in reactor development.

Because the ARMI software is just a framework for other, much larger nuclear models, ARMI does not contain any proprietary or classified information. This allows ARMI to be open-source software. It also greatly simplifies the software design and maintenance. For instance, ARMI does not have any performance requirements. ARMI has been used to model nuclear reactors for over a decade, and in that time the practical reality is that ARMI is quite light weight and >99% of the run time of a simulation occurs in running other nuclear models.

Here are some quick metrics for ARMI’s requirements:

• 140 Requirements in ARMI

  • 0 Preliminary Requirements

  • 140 Accepted Requirements

  • 138 Requirements with implementations

  • 133 Requirements with tests

  • 254 tests linked to Requirements

  • 190 implementations linked to Requirements

1.3. Framework-Related Concepts

This section provides the highest-level requirements for the ARMI framework. These requirements are specific to the idea that ARMI is a framework, that allows for the connection of disparate scientific and nuclear engineer models. The four major pieces of the codebase covered by these requirements are:

• armi.apps - An ARMI simulation is controlled by an ARMI Application.

• armi.plugins - Each Application registers a list of Plugins.

• armi.interfaces - Each Plugin registers a list of Interface.

• armi.operators - The Operator contains a list of Interfaces, which are run in order at each time node.

1.3.1. Functional Requirements

Requirement: The operator package shall provide a means by which to communicate inputs and results between analysis plugins. R_ARMI_OPERATOR_COMM

status: accepted acceptance_criteria: A plugin can access run input data and results from other plugins. basis: This is a foundational design concept in ARMI and is what makes it a framework. subtype: functional testing: T_ARMI_OPERATOR_COMM implementations: I_ARMI_OPERATOR_COMM

Requirement: The operator package shall allow tight coupling between analysis plugins. R_ARMI_OPERATOR_PHYSICS

status: accepted acceptance_criteria: An operator can call each interface multiple times at a given time node, subject to some convergence criteria. basis: Tight coupling is a mechanism that allows for simultaneous convergence of analysis results. subtype: functional testing: T_ARMI_OPERATOR_PHYSICS0, T_ARMI_OPERATOR_PHYSICS1 implementations: I_ARMI_OPERATOR_PHYSICS0, I_ARMI_OPERATOR_PHYSICS1

Requirement: The operator package shall provide a means to perform parallel computations. R_ARMI_OPERATOR_MPI

status: accepted acceptance_criteria: An operator can execute logic dependent on its MPI rank. basis: Parallel computations provide scalable solutions to computational performance. subtype: functional testing: T_ARMI_OPERATOR_MPI0, T_ARMI_OPERATOR_MPI1 implementations: I_ARMI_OPERATOR_MPI

Requirement: ARMI shall allow users to customize how time is discretized for modeling. R_ARMI_FW_HISTORY

status: accepted acceptance_criteria: Specify number of cycles and burn steps and observe the interfaces are run at those time nodes. basis: Analysts will want to model the time evolution of reactors. And discretizing time is a common need to nearly all scientific modeling. subtype: functional testing: T_ARMI_FW_HISTORY2, T_ARMI_FW_HISTORY0, T_ARMI_FW_HISTORY1 implementations: I_ARMI_FW_HISTORY

Requirement: An application shall consist of a collection of plugins. R_ARMI_APP_PLUGINS

status: accepted acceptance_criteria: Construct an ARMI application from a collection of plugins. basis: Plugins are the major mechanism for adding code to a simulations. subtype: functional testing: T_ARMI_APP_PLUGINS implementations: I_ARMI_APP_PLUGINS

Requirement: An operator shall be built from user settings. R_ARMI_OPERATOR_SETTINGS

status: accepted acceptance_criteria: Construct an operator that depends on user settings. basis: Configuring an operator allows users to customize a simulation. subtype: functional testing: T_ARMI_OPERATOR_SETTINGS implementations: I_ARMI_OPERATOR_SETTINGS

Requirement: The operator package shall expose an ordered list of interfaces that is looped over at each time step. R_ARMI_OPERATOR_INTERFACES

status: accepted acceptance_criteria: Show that interfaces are executed in order at each time step. basis: Reactor modeling is controlled by looping over an ordered list of interfaces at each time node. subtype: functional testing: T_ARMI_OPERATOR_INTERFACES implementations: I_ARMI_OPERATOR_INTERFACES0, I_ARMI_OPERATOR_INTERFACES

Requirement: The interface package shall allow code execution at important operational points in time. R_ARMI_INTERFACE

status: accepted acceptance_criteria: Show that interfaces allow code to be execute at BOL, EOL, BOC, and EOC. basis: Defining code to be run at specific times allows users to control the reactor simulation and analysis. subtype: functional testing: T_ARMI_INTERFACE implementations: I_ARMI_INTERFACE

Requirement: The plugin module shall allow the creation of a plugin, which adds code to the application. R_ARMI_PLUGIN

status: accepted acceptance_criteria: Load a plugin into an application. basis: The primary way developers will add code to the simulation is by writing an ARMI plugin. subtype: functional testing: T_ARMI_PLUGIN_REGISTER implementations: I_ARMI_PLUGIN

Requirement: Plugins shall add interfaces to the operator. R_ARMI_PLUGIN_INTERFACES

status: accepted acceptance_criteria: Register multiple interfaces from a given plugin. basis: The mechanism by which plugins add code to the simulation is that plugins can register interfaces on the operator. subtype: functional testing: T_ARMI_PLUGIN_INTERFACES0, T_ARMI_PLUGIN_INTERFACES1 implementations: I_ARMI_PLUGIN_INTERFACES

Requirement: Plugins shall have the ability to add parameters to the reactor data model. R_ARMI_PLUGIN_PARAMS

status: accepted acceptance_criteria: Register multiple parameters from a given plugin. basis: An important feature of plugins is that they can add parameters to the reactor model, thus increasing the variety of physical values the simulations can track. subtype: functional testing: T_ARMI_PLUGIN_PARAMS implementations: I_ARMI_PLUGIN_PARAMS

Requirement: Plugins shall have the ability to add custom settings to the simulation. R_ARMI_PLUGIN_SETTINGS

status: accepted acceptance_criteria: Add multiple settings from a given plugin. basis: An important feature of plugins is that they can add settings that can be used to configure a simulation. subtype: functional testing: T_ARMI_PLUGIN_SETTINGS implementations: I_ARMI_PLUGIN_SETTINGS

1.4. Bookkeeping Package

This section provides requirements for the armi.bookkeeping package within the framework, which handles data persistence, including storage and recovery, report generation, data visualization, and debugging.

1.4.1. Functional Requirements

Requirement: The database package shall save a copy of the user settings associated with the run. R_ARMI_DB_CS

status: accepted acceptance_criteria: Save and retrieve the user settings from the database. basis: This supports traceability and restart ability. subtype: functional testing: T_ARMI_DB_CS implementations: I_ARMI_DB_CS

Requirement: The database package shall save a copy of the reactor blueprints associated with the run. R_ARMI_DB_BP

status: accepted acceptance_criteria: Save and retrieve the blueprints from the database. basis: This supports traceability and restart ability. subtype: functional testing: T_ARMI_DB_BP implementations: I_ARMI_DB_BP

Requirement: The database shall store reactor state data at specified points in time. R_ARMI_DB_TIME

status: accepted acceptance_criteria: Save and load a reactor from a database at specified point in time and show parameters are appropriate. basis: Loading a reactor from a database is needed for follow-on analysis. subtype: functional testing: T_ARMI_DB_TIME1, T_ARMI_DB_TIME0 implementations: I_ARMI_DB_TIME1, I_ARMI_DB_TIME0

Requirement: ARMI shall allow runs at a particular time node to be re-instantiated from a snapshot. R_ARMI_SNAPSHOT_RESTART

status: accepted acceptance_criteria: After restarting a run, the reactor time node and power has been correctly reset. basis: Analysts need to do follow-on analysis on detailed treatments of particular time nodes. subtype: functional testing: T_ARMI_SNAPSHOT_RESTART implementations: I_ARMI_SNAPSHOT_RESTART

Requirement: The database shall store system attributes during a simulation. R_ARMI_DB_QA

status: accepted acceptance_criteria: Demonstrate that system attributes are stored in a database after it is initialized. basis: Storing system attributes provides QA traceability. subtype: functional testing: T_ARMI_DB_QA0, T_ARMI_DB_QA1 implementations: I_ARMI_DB_QA

Requirement: ARMI shall allow for previously calculated reactor state data to be retrieved within a run. R_ARMI_HIST_TRACK

status: accepted acceptance_criteria: Demonstrate that a set of parameters stored at differing time nodes can be recovered. basis: Retrieval of calculated run data from a previous time node within a run supports time-based data integration. subtype: functional testing: T_ARMI_HIST_TRACK0, T_ARMI_HIST_TRACK1 implementations: I_ARMI_HIST_TRACK

1.4.2. Software Attributes

Requirement: The database produced shall be agnostic to programming language. R_ARMI_DB_H5

status: accepted acceptance_criteria: Open an output file in the h5 format. basis: Analysts should be free to use the data in any programming language they choose. subtype: attribute testing: T_ARMI_DB_H5 implementations: I_ARMI_DB_H51

1.4.3. I/O Requirements

Requirement: ARMI shall allow extra data to be saved from a run, at specified time nodes. R_ARMI_SNAPSHOT

status: accepted acceptance_criteria: Snapshot logic can be called for a given set of time nodes. basis: Analysts need to do follow-on analysis on detailed treatments of particular time nodes. subtype: io testing: T_ARMI_SNAPSHOT0, T_ARMI_SNAPSHOT1 implementations: I_ARMI_SNAPSHOT0

1.5. Cases Package

This section provides requirements for the armi.cases package within the framework, which is responsible for running and analyzing ARMI-based cases and case suites for an application. This includes functionalities to serialize and deserialize case inputs for input modification, tracking the status of a case, and running simulations.

1.5.1. Functional Requirements

Requirement: The case package shall provide a generic mechanism that will allow a user to run a simulation. R_ARMI_CASE

status: accepted acceptance_criteria: Build a case and initialize a simulation. basis: Most workflows rely on this capability. subtype: functional testing: T_ARMI_CASE implementations: I_ARMI_CASE

Requirement: The case package shall provide a tool to run multiple cases at the same time or with dependence on other cases. R_ARMI_CASE_SUITE

status: accepted acceptance_criteria: Build a suite of cases with dependence and run them. basis: Many workflows rely on this capability. subtype: functional testing: T_ARMI_CASE_SUITE implementations: I_ARMI_CASE_SUITE

Requirement: The case package shall provide a generic mechanism to allow users to modify user inputs in a collection of cases. R_ARMI_CASE_MOD

status: accepted acceptance_criteria: Load user inputs and build a collection of cases that contain programmatically-perturbed inputs. basis: This capability is needed by analysis workflows such as parameter studies and uncertainty quantification. subtype: functional testing: T_ARMI_CASE_MOD0, T_ARMI_CASE_MOD1, T_ARMI_CASE_MOD2 implementations: I_ARMI_CASE_MOD1, I_ARMI_CASE_MOD0

1.5.2. I/O Requirements

Requirement: The case package shall have the ability to load user inputs and perform input validation checks. R_ARMI_CASE_CHECK

status: accepted acceptance_criteria: Load user inputs and perform validation checks. basis: Most workflows rely on this capability. subtype: io testing: T_ARMI_CASE_CHECK implementations: I_ARMI_CASE_CHECK

1.6. Command Line Interface Package

This section provides requirements for the armi.cli package. This package is responsible for providing user entry points to an ARMI-based application as a Command Line Interface (CLI). This package allows for developers to create their own automated work flows including: case submission, user setting validation, data migrations, and more.

1.6.1. Functional Requirements

Requirement: The cli package shall provide a generic CLI for developers to build their own CLI. R_ARMI_CLI_GEN

status: accepted acceptance_criteria: Create an entry point, pass it arguments, and invoke it. basis: Provides extensibility of the system behavior for an application to implement analysis workflows. subtype: functional testing: T_ARMI_CLI_GEN0, T_ARMI_CLI_GEN1, T_ARMI_CLI_GEN2 implementations: I_ARMI_CLI_GEN

1.6.2. I/O Requirements

Requirement: The cli package shall provide a basic CLI which allows users to start an ARMI simulation. R_ARMI_CLI_CS

status: accepted acceptance_criteria: Invoke an ARMI CLI. basis: This is relied upon for most users to submit jobs to a cluster. subtype: io testing: T_ARMI_CLI_CS0, T_ARMI_CLI_CS1, T_ARMI_CLI_CS2 implementations: I_ARMI_CLI_CS

1.7. Materials Package

This section provides requirements for the armi.materials package within the framework, which contains ARMI’s system for defining materials. The materials system in ARMI allows for an extreme amount of flexibility in defining materials with temperature-dependent properties like density, linear expansion factor, and the like.

ARMI also comes packaged with a small set of basic materials, though these are meant only as example materials and (because ARMI is open source) these materials can not include proprietary or classified information. As such, we explicitly forbid the use of the example ARMI materials in safety-related modeling and will not be writing requirements on those materials.

1.7.1. Functional Requirements

Requirement: The materials package shall allow for material classes to be searched across packages in a defined namespace. R_ARMI_MAT_NAMESPACE

status: accepted acceptance_criteria: Import a material class from a package in the ARMI default namespace. basis: This is just a design choice in ARMI, to define how new material definitions are added to a simulation. subtype: functional testing: T_ARMI_MAT_NAMESPACE0, T_ARMI_MAT_NAMESPACE1 implementations: I_ARMI_MAT_NAMESPACE

Requirement: The materials package shall allow for multiple material collections to be defined with an order of precedence in the case of duplicates. R_ARMI_MAT_ORDER

status: accepted acceptance_criteria: Only the preferred material class is returned when multiple material classes with the same name are defined. basis: The ability to represent physical material properties is a basic need for nuclear modeling. subtype: functional testing: T_ARMI_MAT_ORDER implementations: I_ARMI_MAT_ORDER

Requirement: The materials package shall provide the capability to retrieve material properties at different temperatures. R_ARMI_MAT_PROPERTIES

status: accepted acceptance_criteria: Instantiate a Material instance and show that the instance has the appropriate method names defined and examine the methods signatures to ensure they allow for temperature inputs. basis: The ability to represent physical material properties is a basic need for nuclear modeling. subtype: functional testing: T_ARMI_MAT_PROPERTIES0, T_ARMI_MAT_PROPERTIES2, T_ARMI_MAT_PROPERTIES3, T_ARMI_MAT_PROPERTIES1 implementations: I_ARMI_MAT_PROPERTIES

Requirement: The materials package shall allow for user-input to impact the materials in a component. R_ARMI_MAT_USER_INPUT

status: accepted acceptance_criteria: Instantiate a reactor from blueprints that uses the material modifications and show that the modifications are used. basis: The ability to represent physical material properties is a basic need for nuclear modeling. subtype: functional testing: T_ARMI_MAT_USER_INPUT3, T_ARMI_MAT_USER_INPUT4, T_ARMI_MAT_USER_INPUT5, T_ARMI_MAT_USER_INPUT0, T_ARMI_MAT_USER_INPUT1, T_ARMI_MAT_USER_INPUT2 implementations: I_ARMI_MAT_USER_INPUT0, I_ARMI_MAT_USER_INPUT1, I_ARMI_MAT_USER_INPUT2

Requirement: Materials shall generate nuclide mass fractions at instantiation. R_ARMI_MAT_FRACS

status: accepted acceptance_criteria: Show that the material mass fractions are populated when the object is created. basis: The ability to represent physical material properties is a basic need for nuclear modeling. subtype: functional testing: T_ARMI_MAT_FRACS4, T_ARMI_MAT_FRACS0, T_ARMI_MAT_FRACS1, T_ARMI_MAT_FRACS2, T_ARMI_MAT_FRACS3, T_ARMI_MAT_FRACS5 implementations: I_ARMI_MAT_FRACS

Requirement: The materials package shall provide a class for fluids that defines the thermal expansion coefficient as identically zero. R_ARMI_MAT_FLUID

status: accepted acceptance_criteria: Instantiate a Fluid material and show that its linear expansion is identically zero. basis: Thermal expansion coefficients need to be zero for fluids so that fluid components cannot drive thermal expansion of their own or linked component dimensions. subtype: functional testing: T_ARMI_MAT_FLUID1, T_ARMI_MAT_FLUID2, T_ARMI_MAT_FLUID0 implementations: I_ARMI_MAT_FLUID

1.8. Nuclide Directory Package

This section provides requirements for the armi.nucDirectory package within the framework, which is responsible for defining elemental and isotopic information that is used for reactor physics evaluations.

1.8.1. Functional Requirements

Requirement: The nucDirectory package shall provide an interface for querying basic data for elements of the periodic table. R_ARMI_ND_ELEMENTS

status: accepted acceptance_criteria: Query elements by Z, name, and symbol. basis: Element data is needed for converting between mass and number fractions, expanding elements into isotopes, and other tasks. subtype: functional testing: T_ARMI_ND_ELEMENTS0, T_ARMI_ND_ELEMENTS1, T_ARMI_ND_ELEMENTS2, T_ARMI_ND_ELEMENTS3, T_ARMI_ND_ELEMENTS4 implementations: I_ARMI_ND_ELEMENTS0, I_ARMI_ND_ELEMENTS1

Requirement: The nucDirectory package shall provide an interface for querying basic data for important isotopes and isomers. R_ARMI_ND_ISOTOPES

status: accepted acceptance_criteria: Query isotopes and isomers by name, label, MC2-3 ID, MCNP ID, and AAAZZZS ID. basis: Isotope data is used to aid in construction of cross-section generation models, to convert between mass and number fractions, and other tasks. subtype: functional testing: T_ARMI_ND_ISOTOPES0, T_ARMI_ND_ISOTOPES1, T_ARMI_ND_ISOTOPES2, T_ARMI_ND_ISOTOPES3, T_ARMI_ND_ISOTOPES4, T_ARMI_ND_ISOTOPES6, T_ARMI_ND_ISOTOPES5 implementations: I_ARMI_ND_ISOTOPES0, I_ARMI_ND_ISOTOPES1, I_ARMI_ND_ISOTOPES2, I_ARMI_ND_ISOTOPES3, I_ARMI_ND_ISOTOPES7, I_ARMI_ND_ISOTOPES4, I_ARMI_ND_ISOTOPES5, I_ARMI_ND_ISOTOPES6

Requirement: The nucDirectory package shall store data separately from code. R_ARMI_ND_DATA

status: accepted acceptance_criteria: The nucDirectory element, isotope, and isomer data is stored in plain text files in a folder next to the code. basis: Storing data separately from code is good practice in scientific programs. subtype: functional testing: T_ARMI_ND_DATA0, T_ARMI_ND_DATA1, T_ARMI_ND_DATA2 implementations: I_ARMI_ND_DATA0, I_ARMI_ND_DATA1

1.9. Nuclear Data I/O Package

This section provides requirements for the armi.nuclearDataIO package within the framework, which handles reading and writing of standard interface files for reactor physics software (e.g., cross section data).

1.9.1. Functional Requirements

Requirement: The nuclearDataIO package shall be capable of reading and writing ISOTXS files into and out of mutable data structures. R_ARMI_NUCDATA_ISOTXS

status: accepted acceptance_criteria: Read one or more ISOTXS files and its basic input data correctly, and correctly write that data back out to a single file. basis: These files are the MC2 output format. subtype: functional testing: T_ARMI_NUCDATA_ISOTXS0, T_ARMI_NUCDATA_ISOTXS1 implementations: I_ARMI_NUCDATA, I_ARMI_NUCDATA_ISOTXS

Requirement: The nuclearDataIO package shall be capable of reading and writing GAMISO files into and out of mutable data structures. R_ARMI_NUCDATA_GAMISO

status: accepted acceptance_criteria: Read a GAMISO file and its basic input data correctly, and correctly write that data back out. basis: These files are generated by MCC-v3. subtype: functional testing: T_ARMI_NUCDATA_GAMISO0, T_ARMI_NUCDATA_GAMISO1 implementations: I_ARMI_NUCDATA, I_ARMI_NUCDATA_GAMISO

Requirement: The nuclearDataIO package shall be capable of reading and writing GEODST files into and out of mutable data structures. R_ARMI_NUCDATA_GEODST

status: accepted acceptance_criteria: Read a GEODST file and its basic input data correctly, and correctly write that data back out. basis: These files are generated by DIF3D. subtype: functional testing: T_ARMI_NUCDATA_GEODST0, T_ARMI_NUCDATA_GEODST1 implementations: I_ARMI_NUCDATA, I_ARMI_NUCDATA_GEODST

Requirement: The nuclearDataIO package shall be capable of reading and writing DIF3D files into and out of mutable data structures. R_ARMI_NUCDATA_DIF3D

status: accepted acceptance_criteria: Read a DIF3D file and its basic input data correctly, and correctly write that data back out. basis: These files are used in DIF3D. subtype: functional testing: T_ARMI_NUCDATA_DIF3D0, T_ARMI_NUCDATA_DIF3D1, T_ARMI_NUCDATA_DIF3D2 implementations: I_ARMI_NUCDATA, I_ARMI_NUCDATA_DIF3D

Requirement: The nuclearDataIO package shall be capable of reading and writing PMATRX files into and out of mutable data structures. R_ARMI_NUCDATA_PMATRX

status: accepted acceptance_criteria: Read a PMATRX file and its basic input data correctly, and correctly write that data back out. basis: These files are generated by MCC-v3 and used in GAMSOR. subtype: functional testing: T_ARMI_NUCDATA_PMATRX implementations: I_ARMI_NUCDATA, I_ARMI_NUCDATA_PMATRX

Requirement: The nuclearDataIO package shall be capable of reading and writing DLAYXS files into and out of mutable data structures. R_ARMI_NUCDATA_DLAYXS

status: accepted acceptance_criteria: Read a DLAYXS file and its basic input data correctly, and correctly write that data back out. basis: These files are used to generate kinetics parameters. subtype: functional testing: T_ARMI_NUCDATA_DLAYXS0, T_ARMI_NUCDATA_DLAYXS1 implementations: I_ARMI_NUCDATA, I_ARMI_NUCDATA_DLAYXS

Requirement: The nuclearDataIO package shall be able to compute macroscopic cross sections from microscopic cross sections and number densities. R_ARMI_NUCDATA_MACRO

status: accepted acceptance_criteria: Compute macroscopic cross sections from microscopic cross sections and number densities. basis: Macroscopic cross sections are needed by many analysts. subtype: functional testing: T_ARMI_NUCDATA_MACRO implementations: I_ARMI_NUCDATA_MACRO

1.10. Physics Package

This section provides requirements for the armi.physics package within the framework, which contains interfaces for important physics modeling and analysis in nuclear reactors. It is important to note that ARMI is a framework, and as such does not generally include the actual science or engineering calculations for these topics. For instance, ARMI has an interface for “safety analysis”, but this interface is just a place for developers to implement their own safety analysis code. It would be inappropriate to include the actual science or engineering calculations for a detailed safety analysis of a particular reactor in ARMI because ARMI is meant only to house the code to let nuclear modeling and analysis work, not the analysis itself.

1.10.1. Functional Requirements

Requirement: ARMI shall ensure that the computed block-wise power is consistent with the power specified in the reactor data model. R_ARMI_FLUX_CHECK_POWER

status: accepted acceptance_criteria: Test that throws an error when the summed block-wise powers does not match the specified total power. basis: This requirement ensures that neutronics solver scales the neutron flux appropriately such that the computed block-wise power captures the specified global power. subtype: functional testing: T_ARMI_FLUX_CHECK_POWER implementations: I_ARMI_FLUX_CHECK_POWER

Requirement: ARMI shall provide an interface for querying options relevant to neutronics solvers. R_ARMI_FLUX_OPTIONS

status: accepted acceptance_criteria: The interface correctly returns specified neutronics solver options. basis: Reactor analysts will want to use popular neutronics solvers, e.g. DIF3D-Variant. subtype: functional testing: T_ARMI_FLUX_OPTIONS_CS, T_ARMI_FLUX_OPTIONS_R implementations: I_ARMI_FLUX_OPTIONS

Requirement: ARMI shall allow modification of the reactor geometry when needed for neutronics solver execution. R_ARMI_FLUX_GEOM_TRANSFORM

status: accepted acceptance_criteria: Geometry transformations are performed before executing a neutronics solve. basis: Axial expansion can cause a disjointed mesh which cannot be resolved by deterministic neutronics solvers. subtype: functional testing: T_ARMI_FLUX_GEOM_TRANSFORM_ORDER, T_ARMI_FLUX_GEOM_TRANSFORM_CONV implementations: I_ARMI_FLUX_GEOM_TRANSFORM

Requirement: ARMI shall calculate neutron reaction rates for a given block. R_ARMI_FLUX_RX_RATES

status: accepted acceptance_criteria: Calculate accurate reaction rates for a given multigroup flux and cross section library for a wide collection of Blocks. basis: This is a generic ARMI feature implemented to aid in calculating dose, converting results calculated on one mesh to another, and for comparing reaction rates against experiments. subtype: functional testing: T_ARMI_FLUX_RX_RATES, T_ARMI_FLUX_RX_RATES_BY_XS_ID implementations: I_ARMI_FLUX_RX_RATES

Requirement: ARMI shall be able to calculate DPA and DPA rates from a multigroup neutron flux and DPA cross sections. R_ARMI_FLUX_DPA

status: accepted acceptance_criteria: The DPA rate is calculated for a composite with an associated multi-group neutron flux. basis: DPA rates are necessary for fuel performance calculations. subtype: functional testing: T_ARMI_FLUX_DPA implementations: I_ARMI_FLUX_DPA

Requirement: The isotopicDepletion package shall have the ability to generate cross-section tables from a CCCC-based library in a user-specified format. R_ARMI_DEPL_TABLES

status: accepted acceptance_criteria: Produce a table with the specified formatting containing the appropriate cross sections. basis: Depletion solvers require cross-sections to be supplied from external sources if not using built-in cross sections. subtype: functional testing: T_ARMI_DEPL_TABLES

Requirement: The isotopicDepletion package shall provide a base class to track depletable composites. R_ARMI_DEPL_ABC

status: accepted acceptance_criteria: Store and retrieve depletable objects. basis: Depletion analysis may want a way to track depletable composites. subtype: functional testing: T_ARMI_DEPL_ABC

Requirement: The neutronics package shall provide the neutron energy group bounds for a given group structure. R_ARMI_EG_NE

status: accepted acceptance_criteria: Return the correct energy bounds. basis: The bounds define the energy groupings. subtype: functional testing: T_ARMI_EG_NE0, T_ARMI_EG_NE1 implementations: I_ARMI_EG_NE

Requirement: The neutronics package shall return the energy group index which contains the fast energy threshold. R_ARMI_EG_FE

status: accepted acceptance_criteria: Identify the correct energy group for a given energy threshold. basis: The energy groups are only useful if a developer can find the correct one easily. subtype: functional testing: T_ARMI_EG_FE implementations: I_ARMI_EG_FE

Requirement: The neutronics package shall be able to build macroscopic cross sections for all blocks. R_ARMI_MACRO_XS

status: accepted acceptance_criteria: Calculate the macroscopic cross sections for a block. basis: Most steady-state neutronics workflows will rely on this capability. subtype: functional testing: T_ARMI_MACRO_XS implementations: I_ARMI_MACRO_XS

Requirement: The executers module shall provide the ability to run external calculations on an ARMI reactor with configurable options. R_ARMI_EX

status: accepted acceptance_criteria: Execute a mock external calculation based on an ARMI reactor. basis: An ARMI plugin needs to be able to to wrap an external executable. subtype: functional testing: T_ARMI_EX implementations: I_ARMI_EX0, I_ARMI_EX1

Requirement: The fuel cycle package shall allow for user-defined assembly shuffling logic to update the reactor model based on reactor state. R_ARMI_SHUFFLE

status: accepted acceptance_criteria: Execute user-defined shuffle operations based on a reactor model. basis: Shuffle operations can be based on assemblies' burnup state, which may not be known at the start of a run. subtype: functional testing: T_ARMI_SHUFFLE implementations: I_ARMI_SHUFFLE

Requirement: The fuel cycle package shall be capable of leaving user-specified blocks in place during shuffling operations. R_ARMI_SHUFFLE_STATIONARY

status: accepted acceptance_criteria: Shuffle an assembly while leaving a specified block in place. basis: It may be desirable to leave certain blocks, such as grid plates, in place. subtype: functional testing: T_ARMI_SHUFFLE_STATIONARY0, T_ARMI_SHUFFLE_STATIONARY1 implementations: I_ARMI_SHUFFLE_STATIONARY0, I_ARMI_SHUFFLE_STATIONARY1

Requirement: A hexagonal assembly shall support rotating around the z-axis in 60 degree increments. R_ARMI_ROTATE_HEX

status: accepted acceptance_criteria: After rotating a hexagonal assembly, spatial data corresponds to rotating the original assembly data. basis: Rotation of assemblies is common during operation, and requires updating the location of physics data assigned on the assembly. subtype: functional testing: T_ARMI_ROTATE_HEX_ASSEM, T_ARMI_ROTATE_HEX_BLOCK, T_ARMI_ROTATE_HEX_BOUNDARY, T_ARMI_ROTATE_HEX_PIN_LOCS, T_ARMI_ROTATE_HEX_PIN_COORDS, T_ARMI_ROTATE_HEX_CHILD_LOCS implementations: I_ARMI_ROTATE_HEX_ASSEM, I_ARMI_ROTATE_HEX_BLOCK

Requirement: The framework shall provide an algorithm for rotating hexagonal assemblies to equalize burnup. R_ARMI_ROTATE_HEX_BURNUP

status: accepted acceptance_criteria: After rotating a hexagonal assembly, confirm the pin with the highest burnup is in the same sector as pin with the lowest power in the high burnup pin's ring. basis: Rotating of assemblies to minimize burnup helps maximize fuel utilization and reduces power peaking. subtype: functional testing: T_ARMI_ROTATE_HEX_BURNUP implementations: I_ARMI_ROTATE_HEX_BURNUP

Requirement: The cross-section group manager package shall run before cross sections are calculated. R_ARMI_XSGM_FREQ

status: accepted acceptance_criteria: Initiate the cross-section group manager by the same setting that intiates calculating cross sections. And ensure the cross-section group manager always runs before cross sections are calculated. basis: The cross section groups need to be up to date with the core state at the time that the Lattice Physics Interface is called. subtype: functional testing: T_ARMI_XSGM_FREQ0, T_ARMI_XSGM_FREQ1, T_ARMI_XSGM_FREQ2, T_ARMI_XSGM_FREQ3, T_ARMI_XSGM_FREQ4, T_ARMI_XSGM_FREQ5 implementations: I_ARMI_XSGM_FREQ0, I_ARMI_XSGM_FREQ1, I_ARMI_XSGM_FREQ2, I_ARMI_XSGM_FREQ3

Requirement: The cross-section group manager package shall create separate collections of blocks for each combination of user-specified XS type and burnup group. R_ARMI_XSGM_CREATE_XS_GROUPS

status: accepted acceptance_criteria: Create cross section groups and their representative blocks. basis: This helps improve the performance of downstream cross section calculations. subtype: functional testing: T_ARMI_XSGM_CREATE_XS_GROUPS implementations: I_ARMI_XSGM_CREATE_XS_GROUPS

Requirement: The cross-section group manager package shall provide routines to create representative blocks for each collection based on user-specified XS type and burnup group. R_ARMI_XSGM_CREATE_REPR_BLOCKS

status: accepted acceptance_criteria: Create representative blocks using volume-weighted averaging and custom cylindrical averaging. basis: The Lattice Physics Interface needs a representative block from which to generate a lattice physics input file. subtype: functional testing: T_ARMI_XSGM_CREATE_REPR_BLOCKS0, T_ARMI_XSGM_CREATE_REPR_BLOCKS1 implementations: I_ARMI_XSGM_CREATE_REPR_BLOCKS0, I_ARMI_XSGM_CREATE_REPR_BLOCKS1, I_ARMI_XSGM_CREATE_REPR_BLOCKS2

1.11. Reactors Package

This section provides requirements for the armi.reactors package within the framework, unsurprisingly this is the largest package in ARMI. In this package are sub-packages for fully defining a nuclear reactor, starting from blueprints and all the way through defining the full reactor data model. It is this reactor data object that is critical to the framwork; this is how different reactor modeling tools share information.

1.11.1. Functional Requirements

Requirement: The reactor data model shall contain one core and a collection of ex-core objects, all composites. R_ARMI_R

status: accepted acceptance_criteria: Build a reactor data model from a blueprint file, and show it has a core and a spent fuel pool. basis: A shared reactor data model is a fundamental concept in ARMI. subtype: functional testing: T_ARMI_R implementations: I_ARMI_R

Requirement: Assemblies shall be retrievable from the core object by name and location. R_ARMI_R_GET_ASSEM

status: accepted acceptance_criteria: Retrieve assemblies from the core by name and location. basis: Useful for analysis, particularly mechanical and control rod analysis. subtype: functional testing: T_ARMI_R_GET_ASSEM0, T_ARMI_R_GET_ASSEM1 implementations: I_ARMI_R_GET_ASSEM0, I_ARMI_R_GET_ASSEM1

Requirement: The core shall be able to construct a mesh based on its blocks. R_ARMI_R_MESH

status: accepted acceptance_criteria: Construct a mesh from a core object. basis: Preservation of material and geometry boundaries is needed for accurate physics calculations. subtype: functional testing: T_ARMI_R_MESH implementations: I_ARMI_R_MESH

Requirement: ARMI shall support third-core symmetry for hexagonal cores. R_ARMI_R_SYMM

status: accepted acceptance_criteria: Construct a core of full or 1/3-core symmetry. basis: Symmetric model definitions allow for easier user setup and reduced computational expense. subtype: functional testing: T_ARMI_R_SYMM implementations: I_ARMI_R_SYMM

Requirement: The core shall be able to provide assemblies that are neighbors of a given assembly. R_ARMI_R_FIND_NEIGHBORS

status: accepted acceptance_criteria: Return neighboring assemblies from a given assembly in a core. basis: Useful for analysis, particularly mechanical and control rod analysis. subtype: functional testing: T_ARMI_R_FIND_NEIGHBORS implementations: I_ARMI_R_FIND_NEIGHBORS

Requirement: The parameters package shall provide the capability to define parameters that store values of interest on any Composite. R_ARMI_PARAM

status: accepted acceptance_criteria: Ensure that new parameters can be defined and accessed on a Reactor, Core, Assembly, Block, and Component. basis: The capability to define new parameters is a common need for downstream analysis or plugins. subtype: functional testing: T_ARMI_PARAM0, T_ARMI_PARAM1 implementations: I_ARMI_PARAM0, I_ARMI_PARAM1

Requirement: The parameters package shall allow for some parameters to be defined such that they are not written to the database. R_ARMI_PARAM_DB

status: accepted acceptance_criteria: A parameter can be filtered from inclusion into the list of parameters written to the database. basis: Users will require some parameters to remain unwritten to the database file. subtype: functional testing: T_ARMI_PARAM_DB implementations: I_ARMI_PARAM_DB

Requirement: The parameters package shall provide a way to signal if a parameter needs updating across multiple processes. R_ARMI_PARAM_PARALLEL

status: accepted acceptance_criteria: A parameter has an attribute which signals its last updated status among the processors. basis: Parameters updated on compute nodes must be propogated to the head node. subtype: functional testing: T_ARMI_PARAM_PARALLEL0, T_ARMI_PARAM_PARALLEL1 implementations: I_ARMI_PARAM_PARALLEL

Requirement: The parameters package shall allow for a parameter to be serialized for reading and writing to database files. R_ARMI_PARAM_SERIALIZE

status: accepted acceptance_criteria: The Serializer construct can pack and unpack parameter data. basis: Users need to be able to understand what parameters were involved during a given run after it is completed, both for QA purposes and to begin a new analysis using data from previous analyses. subtype: functional testing: T_ARMI_PARAM_SERIALIZE implementations: I_ARMI_PARAM_SERIALIZE

Requirement: The zones module shall allow for a collection of reactor core locations (a Zone). R_ARMI_ZONE

status: accepted acceptance_criteria: Store and retrieve locations from a zone that corresponds to a reactor. Also, store and retrieve multiple Zone objects from a Zones object. basis: This is a basic feature of ARMI and is useful for reactivity coefficients analysis. subtype: functional testing: T_ARMI_ZONE0, T_ARMI_ZONE1, T_ARMI_ZONE2, T_ARMI_ZONE3, T_ARMI_ZONE4 implementations: I_ARMI_ZONE0, I_ARMI_ZONE1

Requirement: The blocks module shall be able to homogenize the components of a hexagonal block. R_ARMI_BLOCK_HOMOG

status: accepted acceptance_criteria: A homogenized hexagonal block has the same mass, dimensions, and pin locations as the block from which it is derived. basis: Homogenizing blocks can improve performance of the uniform mesh converter. subtype: functional testing: T_ARMI_BLOCK_HOMOG implementations: I_ARMI_BLOCK_HOMOG

Requirement: Blocks shall include information on their location. R_ARMI_BLOCK_POSI

status: accepted acceptance_criteria: Any block can be queried to get absolute location and position. basis: Simulations and post-simulation analysis both require block-level physical quantities. subtype: functional testing: T_ARMI_BLOCK_POSI0, T_ARMI_BLOCK_POSI1 implementations: I_ARMI_BLOCK_POSI0, I_ARMI_BLOCK_POSI1, I_ARMI_BLOCK_POSI2

Requirement: The blocks module shall define a hex-shaped block. R_ARMI_BLOCK_HEX

status: accepted acceptance_criteria: Verify a block can be created that declares a hexagonal shape. basis: Hexagonal blocks are used in some pin-based reactors. subtype: functional testing: T_ARMI_BLOCK_HEX0, T_ARMI_BLOCK_HEX1 implementations: I_ARMI_BLOCK_HEX

Requirement: The blocks module shall return the number of pins in a block, when applicable. R_ARMI_BLOCK_NPINS

status: accepted acceptance_criteria: Return the number of pins in a valid block. basis: This is a common need for analysis of pin-based reactors. subtype: functional testing: T_ARMI_BLOCK_NPINS implementations: I_ARMI_BLOCK_NPINS

Requirement: The assemblies module shall define an assembly as a composite type that contains a collection of blocks. R_ARMI_ASSEM_BLOCKS

status: accepted acceptance_criteria: Validate an assembly's type and the types of its children. basis: ARMI must be able to represent assembly-based reactors. subtype: functional testing: T_ARMI_ASSEM_BLOCKS implementations: I_ARMI_ASSEM_BLOCKS

Requirement: Assemblies shall include information on their location. R_ARMI_ASSEM_POSI

status: accepted acceptance_criteria: Any assembly can be queried to get absolute location and position. basis: Assemblies are an important part of pin-type reactor cores, and almost any analysis that uses assemblies will want to know the location of the assemblies. subtype: functional testing: T_ARMI_ASSEM_POSI0, T_ARMI_ASSEM_POSI1 implementations: I_ARMI_ASSEM_POSI0, I_ARMI_ASSEM_POSI1

Requirement: The flags module shall provide unique identifiers (flags) to enable disambiguating composites. R_ARMI_FLAG_DEFINE

status: accepted acceptance_criteria: No two existing flags have equivalence. basis: Flags are used to determine how objects should be handled. subtype: functional testing: T_ARMI_FLAG_DEFINE implementations: I_ARMI_FLAG_DEFINE

Requirement: The set of unique flags in a run shall be extensible without user knowledge of existing flags' values. R_ARMI_FLAG_EXTEND

status: accepted acceptance_criteria: After adding a new flag, no two flags have equivalence. basis: Plugins are able to define their own flags. subtype: functional testing: T_ARMI_FLAG_EXTEND1, T_ARMI_FLAG_EXTEND0 implementations: I_ARMI_FLAG_EXTEND1, I_ARMI_FLAG_EXTEND0

Requirement: Valid flags shall be convertible to and from strings. R_ARMI_FLAG_TO_STR

status: accepted acceptance_criteria: A string corresponding to a defined flag is correctly converted to that flag, and show that the flag can be converted back to a string. basis: Flags need to be converted to strings for serialization. subtype: functional testing: T_ARMI_FLAG_TO_STR implementations: I_ARMI_FLAG_TO_STR0, I_ARMI_FLAG_TO_STR1

Requirement: ARMI shall be able to convert a hexagonal one-third-core geometry to a full-core geometry, and back again. R_ARMI_THIRD_TO_FULL_CORE

status: accepted acceptance_criteria: Convert a hexagonal 1/3 core reactor to full, and back again. basis: Useful to improve modeling performance, if the analysis can accept the approximation. subtype: functional testing: T_ARMI_THIRD_TO_FULL_CORE0, T_ARMI_THIRD_TO_FULL_CORE1 implementations: I_ARMI_THIRD_TO_FULL_CORE0, I_ARMI_THIRD_TO_FULL_CORE1

Requirement: ARMI shall be able to add and remove assemblies along the 120 degree line in a 1/3 core reactor. R_ARMI_ADD_EDGE_ASSEMS

status: accepted acceptance_criteria: Add and then remove assemblies in a 1/3 core reactor. basis: Helpful for analysis that are using 1/3 core hex reactors subtype: functional testing: T_ARMI_ADD_EDGE_ASSEMS implementations: I_ARMI_ADD_EDGE_ASSEMS0, I_ARMI_ADD_EDGE_ASSEMS1

Requirement: ARMI shall be able to convert a hex core to a representative RZ core. R_ARMI_CONV_3DHEX_TO_2DRZ

status: accepted acceptance_criteria: Convert a hex core into an RZ core. basis: Some downstream analysis requires a 2D R-Z geometry. subtype: functional testing: T_ARMI_CONV_3DHEX_TO_2DRZ implementations: I_ARMI_CONV_3DHEX_TO_2DRZ

Requirement: The axial expansion changer shall perform axial thermal expansion and contraction on solid components within a compatible ARMI assembly according to a given axial temperature distribution. R_ARMI_AXIAL_EXP_THERM

status: accepted acceptance_criteria: Perform thermal expansion due to an applied axial temperature distribution. basis: Axial expansion is used to conserve mass and appropriately capture the reactor state under temperature changes. subtype: functional testing: T_ARMI_AXIAL_EXP_THERM0 implementations: I_ARMI_AXIAL_EXP_THERM

Requirement: The axial expansion changer shall perform axial expansion/contraction given a list of components and corresponding expansion coefficients. R_ARMI_AXIAL_EXP_PRESC

status: accepted acceptance_criteria: Perform axial expansion given a list of components from an assembly and corresponding expansion coefficients. basis: Axial expansion is used to conserve mass and appropriately capture the reactor state under temperature changes. subtype: functional testing: T_ARMI_AXIAL_EXP_PRESC0, T_ARMI_AXIAL_EXP_PRESC1, T_ARMI_AXIAL_EXP_PRESC2 implementations: I_ARMI_AXIAL_EXP_PRESC

Requirement: The axial expansion changer shall perform expansion during core construction based on block heights at a user-specified temperature. R_ARMI_INP_COLD_HEIGHT

status: accepted acceptance_criteria: Perform axial expansion during core construction based on block heights at user-specified temperature. basis: The typical workflow in ARMI applications is to transcribe component dimensions, which are generally given at room temperatures. subtype: functional testing: T_ARMI_INP_COLD_HEIGHT implementations: I_ARMI_INP_COLD_HEIGHT

Requirement: The axial expansion changer shall allow user-specified target axial expansion components on a given block. R_ARMI_MANUAL_TARG_COMP

status: accepted acceptance_criteria: Set a target component and verify it was set correctly. basis: The target axial expansion component influences the conservation of mass in a block. subtype: functional testing: T_ARMI_MANUAL_TARG_COMP implementations: I_ARMI_MANUAL_TARG_COMP

Requirement: The axial expansion changer shall preserve the total height of a compatible ARMI assembly. R_ARMI_ASSEM_HEIGHT_PRES

status: accepted acceptance_criteria: Perform axial expansion and confirm that the height of the compatible ARMI assembly is preserved. basis: Many physics solvers require that the total height of each assembly in the core is consistent. subtype: functional testing: T_ARMI_ASSEM_HEIGHT_PRES implementations: I_ARMI_ASSEM_HEIGHT_PRES

Requirement: The uniform mesh converter shall make a copy of the reactor where the new reactor core has a uniform axial mesh. R_ARMI_UMC

status: accepted acceptance_criteria: Convert a reactor to one where the core has a uniform axial mesh. basis: This is used in the global flux calculations. subtype: functional testing: T_ARMI_UMC implementations: I_ARMI_UMC

Requirement: The uniform mesh converter shall map select parameters from composites on the original mesh to composites on the new mesh. R_ARMI_UMC_PARAM_FORWARD

status: accepted acceptance_criteria: Create a new reactor with the uniform mesh converter and ensure that the flux and power density block-level parameters are mapped appropriately to the new reactor. basis: This is used in the global flux calculations. subtype: functional testing: T_ARMI_UMC_PARAM_FORWARD implementations: I_ARMI_UMC_PARAM_FORWARD

Requirement: The uniform mesh converter shall map select parameters from composites on the new mesh to composites on the original mesh. R_ARMI_UMC_PARAM_BACKWARD

status: accepted acceptance_criteria: Create a new reactor with the uniform mesh converter and ensure that the flux and power density block-level parameters are mapped appropriately back to the original reactor. basis: This is used in the global flux calculations. subtype: functional testing: T_ARMI_UMC_PARAM_BACKWARD0, T_ARMI_UMC_PARAM_BACKWARD1 implementations: I_ARMI_UMC_PARAM_BACKWARD

Requirement: The uniform mesh converter shall try to preserve the boundaries of fuel and control material. R_ARMI_UMC_NON_UNIFORM

status: accepted acceptance_criteria: Create a reactor with slightly non-uniform mesh and verify after the uniform mesh converter the mesh is still non-uniform. basis: Regions with extremely small axial size can cause difficulties for the deterministic neutronics solvers. subtype: functional testing: T_ARMI_UMC_NON_UNIFORM0 implementations: I_ARMI_UMC_NON_UNIFORM

Requirement: The uniform mesh converter shall produce a uniform axial mesh with a size no smaller than a user-specified value. R_ARMI_UMC_MIN_MESH

status: accepted acceptance_criteria: Create a reactor with a mesh that is smaller than the minimum size. After the uniform mesh conversion the new mesh conforms to the user-specified value. basis: Regions with extremely small axial size can cause difficulties for the deterministic neutronics solvers. subtype: functional testing: T_ARMI_UMC_MIN_MESH1, T_ARMI_UMC_MIN_MESH0 implementations: I_ARMI_UMC_MIN_MESH

Requirement: The block converter module shall be able to convert one or more given hexagonal blocks into a single user-configurable representative cylindrical block. R_ARMI_BLOCKCONV_HEX_TO_CYL

status: accepted acceptance_criteria: Create a cylindrical block from one or more given hexagonal blocks and confirm that the cylindrical block has the appropriate volume fractions and temperatures. basis: Needed, for example, for generating 1D cross sections for control rods. subtype: functional testing: T_ARMI_BLOCKCONV_HEX_TO_CYL1, T_ARMI_BLOCKCONV_HEX_TO_CYL0 implementations: I_ARMI_BLOCKCONV_HEX_TO_CYL

Requirement: The block converter module shall be able to homogenize one component into another on a block. R_ARMI_BLOCKCONV

status: accepted acceptance_criteria: Homogenize one component into another from a given block and confirm the new components are appropriate. basis: Needed, for example, for merging wire into coolant or gap into clad to simplify the model. subtype: functional testing: T_ARMI_BLOCKCONV0, T_ARMI_BLOCKCONV1 implementations: I_ARMI_BLOCKCONV0, I_ARMI_BLOCKCONV1

Requirement: The components package shall define a composite corresponding to a physical piece of a reactor. R_ARMI_COMP_DEF

status: accepted acceptance_criteria: Create components, and verify their attributes and parameters. basis: This is a fundamental design choice in ARMI, to describe a physical reactor. subtype: functional testing: T_ARMI_COMP_DEF0, T_ARMI_COMP_DEF1 implementations: I_ARMI_COMP_DEF

Requirement: A component's dimensions shall be calculable for any temperature. R_ARMI_COMP_DIMS

status: accepted acceptance_criteria: Calculate a components dimensions at a variety of temperatures. basis: Users require access to dimensions at perturbed temperatures. subtype: functional testing: T_ARMI_COMP_DIMS0, T_ARMI_COMP_DIMS1 implementations: I_ARMI_COMP_DIMS

Requirement: Components shall be able to compute dimensions, areas, and volumes that reflect its current state. R_ARMI_COMP_VOL

status: accepted acceptance_criteria: Calculate volumes/areas, clear the cache, change the temperature, and recalculate volumes/areas. basis: It is necessary to be able to compute areas and volumes when state changes. subtype: functional testing: T_ARMI_COMP_VOL0, T_ARMI_COMP_VOL1, T_ARMI_COMP_VOL2, T_ARMI_COMP_VOL3, T_ARMI_COMP_VOL4, T_ARMI_COMP_VOL5, T_ARMI_COMP_VOL6, T_ARMI_COMP_VOL7, T_ARMI_COMP_VOL8, T_ARMI_COMP_VOL9, T_ARMI_COMP_VOL10, T_ARMI_COMP_VOL11, T_ARMI_COMP_VOL12, T_ARMI_COMP_VOL13 implementations: I_ARMI_COMP_VOL0, I_ARMI_COMP_VOL1

Requirement: Components shall allow for constituent nuclide fractions to be modified. R_ARMI_COMP_NUCLIDE_FRACS

status: accepted acceptance_criteria: Modify nuclide fractions on a component. basis: The ability to modify nuclide fractions is a common need in reactor analysis. subtype: functional testing: T_ARMI_COMP_NUCLIDE_FRACS0, T_ARMI_COMP_NUCLIDE_FRACS1 implementations: I_ARMI_COMP_NUCLIDE_FRACS0, I_ARMI_COMP_NUCLIDE_FRACS1

Requirement: Components shall be made of one-and-only-one material or homogenized material. R_ARMI_COMP_1MAT

status: accepted acceptance_criteria: Create a component with a given material, and retrieve that material. basis: This is an ARMI design choice. subtype: functional testing: T_ARMI_COMP_1MAT0 implementations: I_ARMI_COMP_1MAT

Requirement: Components shall be associated with material properties. R_ARMI_COMP_MAT

status: accepted acceptance_criteria: Get material properties from a component material. basis: Users require access to material properties for a given component. subtype: functional testing: T_ARMI_COMP_MAT implementations: I_ARMI_COMP_MAT0

Requirement: Components shall enable an ordering based on their outermost component dimensions. R_ARMI_COMP_ORDER

status: accepted acceptance_criteria: Order a collection of components, based on their dimensions. basis: It is desirable to know which components are located physically inside of others. subtype: functional testing: T_ARMI_COMP_ORDER implementations: I_ARMI_COMP_ORDER

Requirement: The components package shall define components with several basic interrogable shapes. R_ARMI_COMP_SHAPES

status: accepted acceptance_criteria: Create a variety of components with different shapes and query their shape information. basis: Modeling real-world reactor geometries requires a variety of shapes. subtype: functional testing: T_ARMI_COMP_SHAPES1, T_ARMI_COMP_SHAPES2, T_ARMI_COMP_SHAPES3, T_ARMI_COMP_SHAPES4 implementations: I_ARMI_COMP_SHAPES0, I_ARMI_COMP_SHAPES1, I_ARMI_COMP_SHAPES2, I_ARMI_COMP_SHAPES3, I_ARMI_COMP_SHAPES4, I_ARMI_COMP_SHAPES5, I_ARMI_COMP_SHAPES6, I_ARMI_COMP_SHAPES7

Requirement: The components package shall handle radial thermal expansion of individual components. R_ARMI_COMP_EXPANSION

status: accepted acceptance_criteria: Calculate radial thermal expansion for a variety components. basis: Users need the ability to model thermal expansion of a reactor core. subtype: functional testing: T_ARMI_COMP_EXPANSION0, T_ARMI_COMP_EXPANSION1 implementations: I_ARMI_COMP_EXPANSION1, I_ARMI_COMP_EXPANSION0

Requirement: The components package shall allow the dimensions of fluid components to change based on the solid components adjacent to them. R_ARMI_COMP_FLUID

status: accepted acceptance_criteria: Determine the dimensions of a fluid component, bounded by solids. basis: The shapes of fluid components are defined externally. subtype: functional testing: T_ARMI_COMP_FLUID, T_ARMI_COMP_FLUID1 implementations: I_ARMI_COMP_FLUID0, I_ARMI_COMP_FLUID1

Requirement: The composites module shall define an arbitrary physical piece of a reactor with retrievable children in a hierarchical data model. R_ARMI_CMP

status: accepted acceptance_criteria: Create a composite with children. basis: This is a fundamental aspect of the ARMI framework. subtype: functional testing: T_ARMI_CMP0, T_ARMI_CMP1 implementations: I_ARMI_CMP0, I_ARMI_CMP1

Requirement: Composites shall be able to be associated with flags. R_ARMI_CMP_FLAG

status: accepted acceptance_criteria: Give a composite one or more flags. basis: Flags are used to provide context as to what a composite object represents. subtype: functional testing: T_ARMI_CMP_FLAG implementations: I_ARMI_CMP_FLAG0, I_ARMI_CMP_FLAG1

Requirement: Composites shall have their own parameter collections. R_ARMI_CMP_PARAMS

status: accepted acceptance_criteria: Query a composite's parameter collection. basis: Parameters should live on the part of the model which they describe. subtype: functional testing: T_ARMI_CMP_PARAMS0, T_ARMI_CMP_PARAMS1 implementations: I_ARMI_CMP_PARAMS

Requirement: The total mass of specified nuclides in a composite shall be retrievable. R_ARMI_CMP_GET_MASS

status: accepted acceptance_criteria: Return the mass of specified nuclides in a composite. basis: Downstream analysis will want to get masses. subtype: functional testing: T_ARMI_CMP_GET_MASS implementations: I_ARMI_CMP_GET_MASS

Requirement: Composites shall allow synchronization of state across compute nodes. R_ARMI_CMP_MPI

status: accepted acceptance_criteria: Synchronize a reactor's state across compute processes. basis: Parallel executions of ARMI require synchronization of reactors on different nodes. subtype: functional testing: T_ARMI_CMP_MPI0, T_ARMI_CMP_MPI1, T_ARMI_CMP_MPI2 implementations: I_ARMI_CMP_MPI

Requirement: The homogenized number densities of specified nuclides in a composite shall be retrievable. R_ARMI_CMP_GET_NDENS

status: accepted acceptance_criteria: Retrieve homogenized number densities of specified nuclides from a composite. basis: The ability to retrieve homogenized number densities is a common need in reactor analysis. subtype: functional testing: T_ARMI_CMP_GET_NDENS0 implementations: I_ARMI_CMP_GET_NDENS

Requirement: Composites shall be able to return number densities for all their nuclides. R_ARMI_CMP_NUC

status: accepted acceptance_criteria: Return the number densities for all nuclides for a variety of composites. basis: Analysts not using lumped fission products need this capability. subtype: functional testing: T_ARMI_CMP_NUC implementations: I_ARMI_CMP_NUC0, I_ARMI_CMP_NUC1

Requirement: The grids package shall allow for pieces of the reactor to be organized into regular-pitch hexagonal lattices (grids). R_ARMI_GRID_HEX

status: accepted acceptance_criteria: Construct a hex grid from pitch and number of rings, and return both. basis: This is necessary for representing reactor geometry. subtype: functional implementations: I_ARMI_GRID_HEX

Requirement: The grids package shall be able to represent 1/3-symmetry or full hexagonal grids. R_ARMI_GRID_SYMMETRY

status: accepted acceptance_criteria: Construct a 1/3 symmetry and full grid and show they have the correct number of constituents. basis: Analysts frequently want symmetrical representations of a reactor for efficiency reasons. subtype: functional implementations: I_ARMI_GRID_SYMMETRY0, I_ARMI_GRID_SYMMETRY1

Requirement: A hexagonal grid with 1/3 symmetry shall be able to determine if a constituent object is in the first third. R_ARMI_GRID_SYMMETRY_LOC

status: accepted acceptance_criteria: Correctly identify an object that is in the first 1/3 and one that is not. basis: Helpful for analysts doing analysis on third-core hex grids. subtype: functional implementations: I_ARMI_GRID_SYMMETRY_LOC

Requirement: A hexagonal grid with 1/3 symmetry shall be capable of retrieving equivalent contents based on 1/3 symmetry. R_ARMI_GRID_EQUIVALENTS

status: accepted acceptance_criteria: Return the zero or 2 elements which are in symmetric positions to a given element. basis: This is necessary for shuffle of 1/3-core symmetry reactor models. subtype: functional implementations: I_ARMI_GRID_EQUIVALENTS

Requirement: Grids shall be able to nest. R_ARMI_GRID_NEST

status: accepted acceptance_criteria: Nest one grid within another. basis: This is typical of reactor geometries, for instance pin grids are nested inside of assembly grids. subtype: functional testing: T_ARMI_GRID_NEST implementations: I_ARMI_GRID_NEST

Requirement: Hexagonal grids shall be either x-type or y-type. R_ARMI_GRID_HEX_TYPE

status: accepted acceptance_criteria: Construct a "points-up" and a "flats-up" grid. basis: This is typical of reactor geometries, for instance pin grids inside of assembly grids. subtype: functional implementations: I_ARMI_GRID_HEX_TYPE

Requirement: The grids package shall be able to store components with multiplicity greater than 1. R_ARMI_GRID_MULT

status: accepted acceptance_criteria: Build a grid with components with multiplicity greater than 1. basis: The blueprints system allows for components with multiplicity greater than 1, when there are components that are compositionally identical. subtype: functional testing: T_ARMI_GRID_MULT implementations: I_ARMI_GRID_MULT

Requirement: The grids package shall be able to return the coordinate location of any grid element in a global coordinate system. R_ARMI_GRID_GLOBAL_POS

status: accepted acceptance_criteria: Return a hexagonal grid element's location. basis: This is a common need of a reactor analysis system. subtype: functional implementations: I_ARMI_GRID_GLOBAL_POS

Requirement: The grids package shall be able to return the location of all instances of grid components with multiplicity greater than 1. R_ARMI_GRID_ELEM_LOC

status: accepted acceptance_criteria: Return a hexagonal grid element's locations when its multiplicity is greater than 1. basis: This is a necessary result of having component multiplicity. subtype: functional implementations: I_ARMI_GRID_ELEM_LOC

1.11.2. I/O Requirements

Requirement: The blueprints package shall allow the user to define a component using a custom text file. R_ARMI_BP_COMP

status: accepted acceptance_criteria: Read a blueprint file and verify a component was correctly created. basis: This is a basic ARMI feature, that we have custom text blueprint files. subtype: io testing: T_ARMI_BP_COMP implementations: I_ARMI_BP_COMP

Requirement: The blueprints package shall allow the user to define a block using a custom text file. R_ARMI_BP_BLOCK

status: accepted acceptance_criteria: Read a blueprint file and verify a block was correctly created with shape, material, and input temperature. basis: This is a basic ARMI feature, that we have custom text blueprint files. subtype: io testing: T_ARMI_BP_BLOCK implementations: I_ARMI_BP_BLOCK

Requirement: The blueprints package shall allow the user to define an assembly using a custom text file. R_ARMI_BP_ASSEM

status: accepted acceptance_criteria: Read a blueprint file and verify a assembly was correctly created. basis: This is a basic ARMI feature, that we have custom text blueprint files. subtype: io testing: T_ARMI_BP_ASSEM implementations: I_ARMI_BP_ASSEM

Requirement: The blueprints package shall allow the user to define a core using a custom text file. R_ARMI_BP_CORE

status: accepted acceptance_criteria: Read a blueprint file and verify a core was correctly created. basis: This is a basic ARMI feature, that we have custom text blueprint files. subtype: io testing: T_ARMI_BP_CORE implementations: I_ARMI_BP_SYSTEMS

Requirement: The blueprints package shall allow the user to define a lattice map in a reactor core using a custom text file. R_ARMI_BP_GRID

status: accepted acceptance_criteria: Read a blueprint file and verify a lattice grid was correctly created at the assembly and pin levels. basis: This is a basic ARMI feature, that we have custom text blueprint files. subtype: io testing: T_ARMI_BP_GRID1, T_ARMI_BP_GRID0 implementations: I_ARMI_BP_GRID

Requirement: The blueprints package shall allow the user to define a reactor, including both a core and a spent fuel pool using a custom text file. R_ARMI_BP_SYSTEMS

status: accepted acceptance_criteria: Read a blueprint file and verify a reactor was correctly created. basis: This is a basic ARMI feature, that we have custom text blueprint files. subtype: io testing: T_ARMI_BP_SYSTEMS implementations: I_ARMI_BP_SYSTEMS

Requirement: The blueprints package shall allow the user to define isotopes which should be depleted. R_ARMI_BP_NUC_FLAGS

status: accepted acceptance_criteria: Read a blueprint file and verify the collection of depleted nuclide flags. basis: This is a basic ARMI feature, that we have custom text blueprint files. subtype: io testing: T_ARMI_BP_NUC_FLAGS0, T_ARMI_BP_NUC_FLAGS1 implementations: I_ARMI_BP_NUC_FLAGS0, I_ARMI_BP_NUC_FLAGS1

Requirement: The blueprints package shall allow the user to produce a valid blueprints file from an in-memory blueprint object. R_ARMI_BP_TO_DB

status: accepted acceptance_criteria: Write a blueprint file from an in-memory blueprint object. basis: The capability to export custom blueprints input files from an in-memory blueprints object is a fundamental ARMI feature. subtype: io testing: T_ARMI_BP_TO_DB1, T_ARMI_BP_TO_DB0 implementations: I_ARMI_BP_TO_DB

1.12. RunLog Module

This section provides requirements for the simulation logging module, armi.runLog, which manages the reporting of messages to the user.

1.12.1. Functional Requirements

Requirement: The runLog module shall allow for a simulation-wide log with user-specified verbosity. R_ARMI_LOG

status: accepted acceptance_criteria: Messages are written to the log with specified verbosity. basis: Logging simulation information is required for analysts to document and verify simulation results. subtype: functional testing: T_ARMI_LOG0, T_ARMI_LOG1, T_ARMI_LOG2, T_ARMI_LOG3, T_ARMI_LOG4, T_ARMI_LOG5, T_ARMI_LOG6, T_ARMI_LOG7 implementations: I_ARMI_LOG

1.12.2. I/O Requirements

Requirement: The runLog module shall allow logging to the screen, to a file, or both. R_ARMI_LOG_IO

status: accepted acceptance_criteria: Messages can be written to log files and log streams. basis: Logging simulation information is required for analysts to document and verify simulation results. subtype: io testing: T_ARMI_LOG_IO0, T_ARMI_LOG_IO1 implementations: I_ARMI_LOG_IO

Requirement: The runLog module shall allow log files to be combined from different processes. R_ARMI_LOG_MPI

status: accepted acceptance_criteria: Messages in different log files can be concatenated. basis: Logging simulation information is required for analysts to document and verify simulation results. subtype: io testing: T_ARMI_LOG_MPI implementations: I_ARMI_LOG_MPI

1.13. Settings Package

This section provides requirements for the armi.settings package, which is responsible for providing a centralized means for users to configure an application. This package can serialize and deserialize user settings from a human-readable text file. When a simulation is being initialized, settings validation is performed to enforce things like type consistency, and to find incompatible settings. To make settings easier to understand and use, once a simulation has been initialized, settings become immutable.

1.13.1. Functional Requirements

Requirement: The settings package shall allow the configuration of a simulation through user settings. R_ARMI_SETTING

status: accepted acceptance_criteria: Create and edit a set of settings that can be used to initialize a run. basis: Settings are how the user configures their run. subtype: functional testing: T_ARMI_SETTING implementations: I_ARMI_SETTING1, I_ARMI_SETTING0

Requirement: All settings must have default values. R_ARMI_SETTINGS_DEFAULTS

status: accepted acceptance_criteria: A setting cannot be created without providing a default value. basis: Enforcing a default recommendation for a setting allows for ease-of-use of the system subtype: functional testing: T_ARMI_SETTINGS_DEFAULTS implementations: I_ARMI_SETTINGS_DEFAULTS

Requirement: Settings shall support rules to validate and customize each setting's behavior. R_ARMI_SETTINGS_RULES

status: accepted acceptance_criteria: Query a setting and make decisions based on its value. basis: Validation of user settings adds quality assurance pedigree and reduces user errors. subtype: functional testing: T_ARMI_SETTINGS_RULES0 implementations: I_ARMI_SETTINGS_RULES

Requirement: The settings package shall supply the total reactor power at each time step of a simulation. R_ARMI_SETTINGS_POWER

status: accepted acceptance_criteria: Retrieve the power fractions series from the operator and access the value at a given time step. basis: Power history is needed by many downstream plugins and methodologies for normalization. subtype: functional testing: T_ARMI_SETTINGS_POWER1, T_ARMI_SETTINGS_POWER0 implementations: I_ARMI_SETTINGS_POWER

Requirement: The settings package shall allow users to define basic metadata for the run. R_ARMI_SETTINGS_META

status: accepted acceptance_criteria: Set and retrieve the basic metadata settings. basis: Storing metadata in the settings file makes it easier for analysts to differentiate many settings files, and describe the simulations they configure. subtype: functional testing: T_ARMI_SETTINGS_META implementations: I_ARMI_SETTINGS_META0, I_ARMI_SETTINGS_META1

1.13.2. I/O Requirements

Requirement: The settings package shall use human-readable, plain-text files as input and output. R_ARMI_SETTINGS_IO_TXT

status: accepted acceptance_criteria: Show a settings object can be created from a text file with a well-specific format, and written back out to a text file. basis: Settings are how the user configures their run. subtype: io testing: T_ARMI_SETTINGS_IO_TXT0, T_ARMI_SETTINGS_IO_TXT1 implementations: I_ARMI_SETTINGS_IO_TXT

1.14. Utilities Package

This section provides requirements for the armi.utils package within the framework, which is one of the smaller high-level packages in ARMI. This package contains a small set of basic utilities which are meant to be generally useful in ARMI and in the wider ARMI ecosystem. While most of the code in this section does not rise to the level of a “requirement”, some does.

1.14.1. Functional Requirements

Requirement: ARMI shall provide a utility to convert mass densities and fractions to number densities. R_ARMI_UTIL_MASS2N_DENS

status: accepted acceptance_criteria: Provide a series of mass densities and fractions and verify the returned number densities. basis: This is a widely used utility. subtype: functional testing: T_ARMI_UTIL_MASS2N_DENS implementations: I_ARMI_UTIL_MASS2N_DENS

Requirement: ARMI shall provide a utility to expand elemental mass fractions to natural nuclides. R_ARMI_UTIL_EXP_MASS_FRACS

status: accepted acceptance_criteria: Expand an element's mass into a list of it's naturally occurring nuclides and their corresponding mass fractions. basis: This is a widely used utility. subtype: functional testing: T_ARMI_UTIL_EXP_MASS_FRACS implementations: I_ARMI_UTIL_EXP_MASS_FRACS

Requirement: ARMI shall provide a utility to format nuclides and densities into an MCNP material card. R_ARMI_UTIL_MCNP_MAT_CARD

status: accepted acceptance_criteria: Create an MCNP material card from a collection of densities. basis: This will be useful for downstream MCNP plugins. subtype: functional testing: T_ARMI_UTIL_MCNP_MAT_CARD implementations: I_ARMI_UTIL_MCNP_MAT_CARD

1.15. Software Attributes

ARMI is a Python-based framework, designed to help tie together various nuclear models, written in a variety of languages. ARMI officially supports Python versions 3.9 and up.

ARMI is heavily tested and used in both Windows and Linux. More specifically, ARMI is always designed to work in the most modern Windows operating system (Windows 10 and Windows 11 currently). Similarly, ARMI is designed to work with fairly modern versions of Ubuntu (22.04 and 24.04 at the time of writing) and Red Hat (RHEL 7 and 8 currently).

Version control for ARMI is achieved using Git and is publicly hosted as open-source software on GitHub. To ensure ARMI remains portable and open-source, it only uses third-party libraries that are similarly fully open-source and that make no onerous demands on ARMI’s distribution or legal status.

ARMI makes use of a huge suite of unit tests to cover the codebase. The tests are run via Continuous Integration (CI) both internally and publicly. Every unit test must pass on every commit to the ARMI main branch. Also, as part of our rigorous quality system, ARMI enforces tight controls on code style using Black as our code formatter and Ruff as our linter.