1. Software Requirement Specification Document (SRSD)¶
1.1. Business Impact¶
The
databasepackage is used to restart runs, analyze results, and determine when changes are introduced to otherwise identical cases in ARMI. Thedatabasepackage is considered high risk.The
reportpackage is one of many tools available for viewing case details and is intended purely for developer or analyst feedback on run specifications and results, not as a means of altering the run. Thus thereportpackage is low risk.The
blueprintspackage interprets user input into an ARMI reactor model. If done incorrectly, ARMI simulations would be unreliable and inaccurate. ARMI is used for informing core designs, engineering calculations, and safety bases; therefore, thebluperintspackage is considered high risk.The
settingspackage contains a substantive amount of the run’s definition. Problems in the settings system can invalidate runs. Fortunately, the errors are easily traced and replicated as the system itself is not complicated. Therefore, thesettingspackage is considered high risk.The
operatorpackage is paramount to every facility the code offers, affecting every aspect of design. Thus, theoperatorpackages is high risk.The
fissionProductModelpackage has substantial impact on the results of the neutronic calculations that affect the plant design. Thus, it falls under the high risk impact level.
#. The reactor package contains the majority of state information throughout a case. Issues in it
could propagate and invalidate results derived from ARMI to perform design and analysis. Therefore, the reactor package is considered high risk.
#. The nucDirectory package contains nuclide-level information including names, weights, symbols, decay-chain, and transmutation information. This information is used for converting mass fractions to number densities, and identifying specific nuclides to be used in used in performing flux and burn-up calculations. Therefore, the nucDirectory package is considered high risk.
#. The nuclearDataIO package is used to read and write nuclear data files which are used as input to global flux solvers, and eventually input into safety calculations via reactivity coefficients. Therefore, the nuclearDataIO package is considered high risk.
1.2. Applicable Documents¶
1.3. Functional Requirements¶
The database shall faithfully represent the possessed information and not alter its contents, retrieving the data exactly as input.
The state information representing as near as possible the entirety of the run when the database write was executed, shall be retrievable to restore the previous case to a particular point in time for further use by analysts.
Given the ubiquity of Python’s None the database shall support its inclusion as a valid entry for data. There will be no support for any abstract data type beyond None.
The report package shall not modify or subvert data integrity as it reports the information out to the user.
Requirement: The settings package shall not accept ambiguous setting definitions. REQ_SETTINGS_UNAMBIGUOUS
  |
Settings defined in the system must have both the intended data type and default value defined, or it is considered incomplete and therefore invalid. Additionally the system shall not accept multiple definitions of the same name.
TODO: This may be tested by a unit test loading in duplicate setting definitions or cases where a definition does not provide adequate details.
No two settings may share names.
TODO: This may be tested by a unit test loading two similar names
Settings shall exist exclusively as a well-defined data type, as chosen by the setting definition.
TODO: This may be tested by unit tests attempting to subvert the contained data type.
Many of the settings will not be altered by the user of a run, and there will likely be too many for a user to deal with on an individual basis. Therefore, most settings will need to function sensibly with their default value. This default value shall always be accessible throughout the runs life cycle.
TODO: This may be tested by unit tests loading and checking values on each setting.
Requirement: Settings shall support more complex rule association to further customize each setting's behavior. REQ_SETTINGS_RULES
|
It shall be possible to support a valid list or range of values for any given setting.
TODO: This may be tested by a unit test attempting to set a value outside a given min/max range.
Requirement: Setting addition, renaming, and removal shall be supported.setting's behavior. REQ_SETTINGS_CHANGES
|
The setting package shall accomodate the introduction of new settings, renaming of old settings, and support the complex deprecation behaviors of settings.
TODO: This may be tested by a unit test containing removed settings references in both input and code references, as well as an additional definition load and use
Each settings file is only genuinely valid with the version of ARMI that generated the file, as settings might change between versions. As a safegaurd of this, the settings system shall alert the user if the version of the settings file does not match the version of ARMI in-memory.
TODO: This may be tested by unit tests with out of date or omitted version information
Requirement: The settings system shall raise an error if the same setting is created twice. REQ_SETTINGS_DUPLICATES
|
When a user creates a setting twice, it shall be detected as an error which is raised to the user.
TODO: This may be tested by unit tests loading and checking settings that have a setting created twice, and failing.
Given user input describing a reactor, ARMI shall construct with equivalent fidelity a software model of the reactor. In particular, ARMI shall appropriately represent the shape, arrangement, connectivity, dimensions, materials (including thermo-mechanical properties), isotopic composition, and temperatures of the reactor.
|
The reactor state shale be made available to users and plugins, which may in turn modify the state. ARMI shall fully define how all aspects of state may be accessed and modified and shall reflect any new state after it is applied. The reactor state shall be represented as evolving either through time (i.e. in a typical cycle-by-cycle analysis) or through a series of control configurations. |
Requirement: The operator package shall provide a means by which to communicate inputs and results between analysis plugins. REQ_OPERATOR_IO
|
The operator package shall receive output from calculation Plugins and store the results on a well-defined central model. A composite pattern shall be used, with a Reactor containing Assemblies containing Blocks, etc.
Requirement: The operator package shall provide a means to perform computations in parallel on a high performance computer. REQ_OPERATOR_PARALLEL
|
Many analysis tasks require high performance computing (HPC), and the operator package shall contain utilities and routines to communicate with an HPC and to facilitate execution of simulations in parallel.
Requirement: The operator package shall allow physics coupling between analysis plugins. REQ_OPERATOR_COUPLING
|
For coupled physics (e.g. neutronics depends on thermal hydraulics depends on neutronics), the operator package shall allow loose and/or tight coupling. Loose coupling is using the values from the previous timestep to update the next timestep. Tight is an operator-splitting iteration until convergence between one or more plugins.
Requirement: The operator package shall allow analysis plugins to be replaced without affecting interfaces in other plugins. REQ_OPERATOR_ANALYSIS
|
Often, a plugin is replaced with a new plugin fulfilling some new requirement. When this happens, the operator package shall isolate required changes to the new plugin. For example, if a fuel performance plugin needs temperatures but the temperature-computing plugin is replaced, the fuel performance plugin should require no changes to work with the drop-in replacement. This requires modular design and standardization in state names.
Based on user settings, the ordering, initialization, and calls to other plugins shall be coordinated by the operator package. The operator package must therefore be aware of dependencies of each plugin.
Requirement: The latticePhysics package will execute the lattice physics code in a parallel or serial fashion depending on the mode. REQ_LATTICE_EXE
|
Requirement: The nucDirectory package shall contain basic nuclide information for a wide range of nuclides. REQ_NUCDIR_INFO
|
The nucDirectory package shall contain the following general information for each nuclide:
name
symbol
natural isotopic abundance of elements
atomic number (Z)
mass number (A)
atomic weight
meta stable state
The software shall be made flexible such that the definition of specific nuclides available (i.e. those used in a version of MCC), can be updated without modifying the code.
TODO: This can be tested by inspecting the logic of the code to retrieve data from a resource file, or by modifying the resource file to create an expected outcome.
The nuclides names shall be unique, and consist of the nuclide’s symbol, mass number, and an indication if it is in a meta-stable state. Elemental nuclides shall omit the mass number, since they represent more than a single mass number. Lumped nuclides shall also have unqiue, user-data identified names.
TODO: A unit test can be used to demonstrate that all nuclide names are unique.
Requirement: The nucDirectory package shall be capable of generating unique 4-character labels. REQ_NUCDIR_LABELS
|
Versions 2 and 3 of MCC allow for unique 6 character labels to be used to reference nuclides. Two characters need to be used to describe the different cross section sets used by the problem. Therefore, every nuclide in ARMI needs to have a unique 4 character representation to use in MCC and the downstream global flux solver.
TODO: A unit test can be used to demonstrate that all nuclides have unique 4-character labels.
Lumped nuclides are bulk defined nuclides that are typically used when modeling fission products. Lumping the nuclides during burnup calculations lowers the problem size without having a significant impact on the results. Consequently, they do not always need to be modeled individually, but can be grouped.
TODO: A unit test can be used to demonstrate that lumped nuclides can be used and created.
The nuclear data libraries available in versions 2 and 3 of MCC do not always allow for nuclide input, and some materials are grouped into elemental nuclides. Iron is an example of this in MCC version 2. Consequently, ARMI needs to be able to model elemental nuclides which represent the entire element, as well as the individual nuclides.
Dummy nuclides, typically written in all capitals as “DUMMY”, are used to truncate the burn chain in order to reduce the problem size without compromising the results.
Requirement: The nucDirectory package shall allow for indexing of nuclide information. REQ_NUCDIR_INDEX
|
The nuclear data files created by physics codes such as MCC and DIF3D may not necessary correspond to the name used within ARMI, it will be necessary to load nuclide information based on a non-ARMI name. The software shall provide lookup mechanisms for nuclide objects based on:
Name
4-character label
MCC versions 2 and 3 IDs
The decay chain is an important step in performing burn-up calculations. The nucDirectory shall contain necessary decay mechanisms:
beta^-
beta^+
alpha
Electron capture
Spontaneous fission
The nucDirectory shall contain the half-life, decay mode(s) with corresponding branch ratio(s) and daughter nuclide(s) of each decay mode being modeled. Since it is possible for the user to define specific nuclides to be modeled, the nucDirectory shall allow for use of different daughter nuclides.
TODO: A unit test can be generated to test that the correct decay chain is present, and that the data matches other resources.
In addition to the decay chain, nuclides may transmute through interactions into other nuclides. The nucDirectory shall contain transmutations including:
n,2n
n,p
n,t
n,fission
n,gamma
n,alpha
The nucDirectory shall contain the transmutation mechanism, branch ratio, and product nuclides of each transmutation being modeled. The nucDirectory shall not contain the cross sections, as these are calculated using lattice physics codes, such as MCC. Since it is possible for the user to define specific nuclides to be modeled, the nucDirectory shall allow optional daughter nuclides.
TODO: A unit test can be generated to test that the correct transmutations are present, and corresponding data matches other resources.
Requirement: The nucDirectory package shall warn the user if there are potential burn-chain faults. REQ_NUCDIR_BURN_CHAIN
|
The user supplies the nuclides to be modeled in the simulation; therefore, it is possible that the user may inadvertently describe a burn-chain that is not complete. The software shall be capable of detecting erroneous user input and terminate the program.
TODO: A unit test can be generated with faulty decay chains to determine that they do not work.
ISOTXS files contain the multi-group microscopic cross sections, and other nuclear data, for each nuclide being modeled. The multi-group cross sections are used throughout ARMI.
The software shall be capable of reading an ISOTXS file into memory, and writing it out to a file that is exactly the same as the original.
TODO: A unit test can be created with reads an ISOTXS file generated by MCC, and then writes out the file to another name. The two files can then be compared using a binary file comparison to demonstrate that the contents of the files are identical.
GAMISO files are generated by MCC-v3, and are the same format as an ISOTXS file. The file contains photon interaction cross sections instead of neutron cross sections.
The software shall be capable of reading a GAMISO file into memory, and writing it out into a file that is exactly the same as the original.
TODO: This can be covered in a unit test; the unit test can be the same as described for ISOTXS files.
PMATRX files contain the gamma production matrix resulting from fission or capture events. Given a neutron flux distribution, and a PMATRX file, the gamma source can be computed and then used to determine gamma transport and heating.
Requirement: The nuclearDataIO package shall be capable of reading a PMATRX file into memory, and writing it out into a file that is exactly the same as the original. R_016A6
|
TODO: This can be covered in a unit test; the unit test can be the same as described for ISOTXS files.
DLAYXS files contain delayed neutron data, such as precursor decay constants and number of neutrons emitted, \(\nu_{\mathrm{delay}}\). The DLAYXS data is used to calculate \(\beta_{\rm{eff}}\), which is used to calculate reactivity coefficients, and consequently in AOO and accident simulations.
The software shall be capable of reading a DLAYXS file into memory, and writing it out into a file that is exactly the same as the original.
TODO: This can be covered in a unit test; the unit test can be the same as described for ISOTXS files.
The software shall be capable merging multiple files of the same type (ISOTXS, PMATRX, etc.) into a single file meeting the specifications. The software shall fail with a descriptive error message if any two nuclides have the same name.
This can be covered in a unit test which runs 3 MCC-v3 cases.
Generate cross sections for a set of nuclides with the xsID=AA 1. Generate cross sections for a set of nuclides with the xsID=AB 1. Generate cross sections with two regions using an input file containing the nuclides of the above two cases.
The third MCC-v3 case will produce a merged ISOTXS file which can be compared to an ISOTXS file generated by merging the output ISOTXS from cases 1 and 2.
Requirement: The nuclearDataIO package shall make the data programmatically available. REQ_NUCDATA_AVAIL
|
The software shall make the nuclear data provided in ISOTXS, GAMISO, PMATRX and DLAYXS available in the form of Python objects, such that it can be used elsewhere in the code, such as in the depletion, nuclear uncertainty quantification, and beta calculations.
When nuclear data files are read, they should be made available in a container object, such as a dictionary, and keyed on the nuclide label (a unique four character nuclide identifier) and the cross section ID, a two character identifier for block type and burnup group.
TODO: This can be covered by a unit test which reads an ISOTXS into a container object, and then obtaining cross sections by using the nuclide label and xsID.
ARMI has a concept of “lumped fission products” that result in more nuclides being in ISOTXS, GAMISO, and PMATRX files than are needed for subsequent calculations. The software shall be capable of removing the unused nuclides from ISOTXS, GAMISO, and PMATRX files. This generally does not apply to DLAYXS files, because they typically only contain nuclides that fission.
TODO: This can be covered by a unit test where a file is read in, a nuclide removed, and then rewritten and reread. The reread file should not contain the removed nuclides.
In order to calculate the uncertainties of our methodology introduced by nuclear data uncertainty, it is necessary to be able to perturb (i.e. modify) specific values within the nuclear data files.
TODO: This can be covered by a unit test where a file is read in, a cross section or relevant piece of data modified, and then rewritten and reread. The reread file should contain the modified data.
1.4. Performance Requirements¶
Requirement: The database representation on disk shall be smaller than the the in-memory Python representation REQ_DB_PERFORMANCE
|
The database implementation shall use lossless compression to reduce the database size.
As the report package is a lightweight interface to write data out to a text based format, and render a few images, the performance costs are entirely negligible and should not burden the run, nor the user’s computer in both memory and processor time.
Requirement: The reactor package shall allow rapid synchronization of state across the network to parallel processors. REQ_REACTOR_PARALLEL
|
For performance, many physics calculations are done in parallel. The reactor must be able to synchronize the state on multiple processors efficiently.
Requirement: The nucDirectory package shall try to prevent data duplication to limit the memory footprint of this information. REQ_NUCDIR_DUPLICATION
|
TODO: Is this testable?
1.5. Software Attributes¶
Requirement: ARMI shall generally support at least one modern Windows and one modern CentOS operating system version. REQ_OS
|
Requirement: The database produced shall be easily accessible in a variety of programming environments beyond Python. REQ_DB_LANGUAGE
|
Requirement: The settings package shall use human-readable, plain-text files as input. REQ_SETTINGS_READABLE
|
The user must be able to read and edit their settings file as plain text in broadly any typical text editor.
1.6. Software Design Constraints¶
Requirement: The report package shall not burden new developers with grasping a complex system. REQ_REPORT_TECH
|
Given the functional requirements of the report package, new developers should be able to understand how to contribute to a report nigh instantly. No new technologies should be introduced to the system as HTML and ASCII are both purely text-based.
Any two ARMI runs with the same input file must produce the same results.
Requirement: The nucDirectory package shall use nuclear data that is contained within the ARMI code base. REQ_NUCDIR_DATA
|
The nucDirectory package shall not use data data retrieved from online sources. The intent here is to prevent inadvertent security risks.
Requirement: The nucDirectory package shall follow a particular naming convention. REQ_NUCDIR_NAMING
|
Other physics codes use the name Am-242 for the metastable state of Am-242, and use Am-242g for the ground state.
1.7. Interface I/O Requirements¶
Requirement: The setting system shall render a view of every defined setting as well as the key attributes associated with it REQ_SETTINGS_REPORT
|
Utilizing the documentation of the ARMI project the settings system shall contribute a page containing a table summary of the settings included in the system.
TODO: This is completed by the Settings Report.
Requirement: The latticePhysics package will write input files for the desired code for each representative block to be modeled. REQ_LATTICE_INPUTS
|
Requirement: The latticePhysics package will use the output(s) to create a reactor library, ``ISOTXS`` or ``COMPXS``, used in the global flux solution. REQ_LATTICE_OUTPUTS
|
The reactor package shall check its inputs for certain obvious errors including unphysical quantities. At a deep level, the reactor package will not attempt to fully validate subtle engineering aspects of the reactor; that is more generally the reason users will want to fully simulate a reactor and cannot be done at input time.