From 6e4bd956e64ef92e41ebc5034098996022c5c6a3 Mon Sep 17 00:00:00 2001 From: jstilley Date: Thu, 15 Sep 2022 10:41:49 -0700 Subject: [PATCH] Responding to Chris' comments. --- doc/requirements/sdid.rst | 54 ++++--------------- doc/requirements/srsd.rst | 106 +++++++++++++++++--------------------- 2 files changed, 56 insertions(+), 104 deletions(-) diff --git a/doc/requirements/sdid.rst b/doc/requirements/sdid.rst index bd5b367a3..fbf91a7ed 100644 --- a/doc/requirements/sdid.rst +++ b/doc/requirements/sdid.rst @@ -17,7 +17,7 @@ The settings package is a long-time feature of ARMI. It was made to fill the nic A good roadmap to understanding the settings system would be to look at the following principle design considerations, going into each one in detail. -* Keep the user's experience with settings as simple as possible. +* Keep the user's experience with settings as simple as possible * Remove setting definitions from code, centralize them, and facilitate definition change * Don't break backwards compatibility * Improve safety around possible misuses and accidents of the settings @@ -29,7 +29,6 @@ Keep the user's experience with settings as simple as possible ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is the principle design restraint for the settings package. In addition to raw implementation complexity, asking developers and users to relearn any alterations to the existing system counts towards total complexity; deeming migration to an equally complex system not worth the effort without stronger incentives. -Historically developers are used to looking up the name of their setting by using a string fed into a collection object and having the value associated with the name returned back. The same behavior was used to assign a new value to the given name in the shared object. This constitutes the vast majority of external interactions with the settings system. Reactor Overview ---------------- @@ -76,19 +75,10 @@ how the object itself behaves. A prime example of this is the GUI. Improve safety around possible misuses and accidents of the settings ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -While simplicity remains a principle concern, some allotment for error prevention has to be allowed. A basic system that can be misused wildly is inherently more complex than one with a little overhead that works to keep nasty surprises as bay. +While simplicity remains a principle concern, some allotment for error prevention has to be allowed. A basic system that can be misused wildly is inherently more complex than one with a little overhead that works to keep nasty surprises at bay. The settings system is written in a defensive fashion, as it's the most frequent location for possible developer and user misuse. Given this, any method from accessing non-existent settings to trying to supply duplicate settings has been written with fail-fast behavior. -In some cases there may be an automated solution to a possible misuse. In general there's nothing overtly wrong -with the litany of checks for safety but it does make the system appear more convoluted to newcomers. Of course, -This small cost is outweighed by the time saved from working through the same resolvable problem in use many times. - -There will always be a need for knowledgable users to communicate with however, as it is unreasonable to attempt to -program in a fool-proof understanding of the physics coded for in the settings system. Such an endeavor would come with great developmental and maintenance costs. - -Most problems these days arise when users make typos or simple editing mistakes when manually adjusting some values in the case settings input files. - Non-dynamic data typing ^^^^^^^^^^^^^^^^^^^^^^^ One specific category of safety in the settings system stems from the nature of data variables in Python. @@ -124,13 +114,9 @@ As mutable objects are encompassed in the list of supported data types, it becam # if we stop the code here, the value in cs['myListSetting'] will not contain # the bad value appended thanks to myList being a deep-copied value - # the following will run 'myList' against any error checking in the system - # either crashing the run or accepting the new value for later use. - cs['myListSetting'] = myList # good! - The customizability of settings ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Yet another error prevention tool is the customizability of individual settings. As mentioned previously a complete understanding of the complex meaning involved in setting values can't be programmed. However by giving each setting more character in the system to stand up on its own against mistakes (e.g. a temperature below absolute zero) can chip away at the burden of the user to need to understand the entirety. +Yet another error prevention tool is the customizability of individual settings. As mentioned previously, a complete understanding of the complex meaning involved in setting values can't be programmed. However, when the user creates a setting, they have the ability to control default values, valid ranges, and other basic sanity checking parameters. Each setting is intended to present a way of answering a question to the user from the system. For example many settings ask questions like what external code engine to utilize for advanced calculations, or what temperature to apply to a particular component. These questions are not open ended and as such usually have a set of rules surrounding their use like no temperatures below absolute zero, or only code engines specified by the following three strings are valid. @@ -161,8 +147,7 @@ grid. In particular, *Assemblies* sit in the 2-D grid on the reactor and *Blocks Setting and getting state variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The *state* is stored on component-level *parameters*. The design and implementation of this subpackage is fully described in -:py:mod:`armi.reactor.parameters`. +The *state* is stored in *parameters* at the ``block`` level and higher. The design and implementation of this subpackage is fully described in :py:mod:`armi.reactor.parameters`. Averaging over children @@ -177,7 +162,7 @@ Computing Homogenized Number Densities """""""""""""""""""""""""""""""""""""" Objects can compute homogenized number densities of each nuclide as required in many nuclear simulations (e.g. DIF3D). The components contained in each block have heterogeneous compositions and dimensions that must be smeared into -a homogeneous block, as shown in figure 1. +a homogeneous block, as shown in Figure 1. To homogenize number densities, conservation of atoms is applied. Consider a a collection of :math:`I` components, each with heterogeneous number density :math:`N_i` and volumes :math:`V_i`. The number of atoms in @@ -228,30 +213,11 @@ is computed as: Hot and input dimensions ^^^^^^^^^^^^^^^^^^^^^^^^ -ARMI treats dimensions and material properties as functions of temperature. However, a pure -physical analogy is challenging for several reasons. These reasons and -the implementation details are explained here. - -For a typical ``component``, users may define most dimensions at any temperature they desire -(the *Input temperature*), as explained in :doc:`/user/inputs/composition_file`. These -dimensions will be thermally-expanded up to the *Hot temperature* as input. For most shapes and -components, this works as expected, however: - -* In Hex geometries, the outer hexagonal boundary is currently limited to be consistent across - all objects in a core. This stems from some physics solver requirements of structured meshes. - Users should set the hot dimension on input. Models that change pitch - as functions of grid-plate and load pad temperatures may be developed in the future. -* The axial heights of **blocks** is complicated to model explicitly because different components - of different materials expand differently at the same temperature. Pure physical analogy would - require independent meshes for the duct, clad, and fuel of every pin. To deal with this, ARMI implements - *exclusively radial thermal expansion* (more details are available in - :doc:`/reference/materials`). As a result of this, users should input the desired hot axial dimensions - of all blocks. Advanced models with multiple axial meshes may be developed at a later time. - -**Component** dimensions are stored as *parameters* at the input temperature and thermally expanded -to the current temperature of the component upon access. To run a case at a specific temperature, -the user sould set the hot and input temperatures to the same value. This can be used to study -isothermal conditions during outages and startup. +ARMI treats dimensions and material properties as functions of temperature. However, a pure physical analogy is challenging for several reasons. These reasons and the implementation details are explained here. + +For a typical ``component``, users may define most dimensions at any temperature they desire (the *Input temperature*), as explained in :doc:`/user/inputs/blueprints`. These dimensions will be thermally-expanded up to the *Hot temperature* as input. For most shapes and components, this works as expected. However, in Hex geometries the outer hexagonal boundary is currently limited to be consistent across all assemblies in a core. This stems from some physics solver requirements of structured meshes. Users should set the hot dimension on input. Models that change pitch as functions of grid-plate and load pad temperatures may be developed in the future. + +**Component** dimensions are stored as *parameters* at the input temperature and thermally expanded to the current temperature of the component upon access. To run a case at a specific temperature, the user should set the hot and input temperatures to the same value. This can be used to study isothermal conditions during outages and startup. ------------------- Requirements Review diff --git a/doc/requirements/srsd.rst b/doc/requirements/srsd.rst index 6b9d073b2..3d8f12f45 100644 --- a/doc/requirements/srsd.rst +++ b/doc/requirements/srsd.rst @@ -10,11 +10,11 @@ Business Impact #. The ``database`` package is used to restart runs, analyze results, and determine when changes are introduced to otherwise identical cases in ARMI. The ``database`` package is considered high risk. #. The ``report`` package 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 the ``report`` package is low risk. #. The ``blueprints`` package 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, the ``bluperints`` package is considered high risk. -#. The ``settings`` package contains a substantive amount of the run's definition. Problems in the settings system can invalidate runs. If a user supplies one piece of input, say the setting value that dictates which reactor-defining loading blueprints files to use, and the system performs misleadingly then any subsequent analysis would be invalidated. As this is the principle system of user interaction with ARMI, poor system design choices would aggravate the user experience and decrease user engagement. Fortunately, the errors are easily traced and replicated as the system itself is not complicated. Therefore, the ``settings`` package is considered high risk. +#. The ``settings`` package 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, the ``settings`` package is considered high risk. #. The ``operator`` package is paramount to every facility the code offers, affecting every aspect of design. Thus, the ``operator`` packages is high risk. #. The ``fissionProductModel`` package 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*. +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. @@ -47,12 +47,6 @@ The state information representing as near as possible the entirety of the run w :id: REEQ_DB_PRIMITIVES :status: needs implementation, needs test -To facilitate the storage of data, any Pythonic primitive data type shall be valid as an entrant into the database. - -.. req:: The database shall not accept abstract data types excluding pythonic ``None``. - :id: REQ_DB_NONE - :status: needs implementation, needs test - 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. .. req:: The report package shall maintain data fidelity. @@ -85,9 +79,17 @@ TODO: This may be tested by a unit test loading in duplicate setting definitions :id: REQ_SETTINGS_UNAMBIGUOUS_TYPE :status: implemented, needs more tests - Settings shall exist exclusively as a single, primitive datatype, as chosen by the setting definition. + Settings shall exist exclusively as a well-defined datatype, as chosen by the setting definition. + + TODO: This may be tested by unit tests attempting to subvert the contained data type. + + .. req:: The settings package shall contain a default state of all settings. + :id: REQ_SETTINGS_DEFAULTS + :status: implemented, needs more tests - 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. .. req:: Settings shall support more complex rule association to further customize each setting's behavior. :id: REQ_SETTINGS_RULES @@ -95,7 +97,7 @@ TODO: This may be tested by a unit test loading in duplicate setting definitions It shall be possible to support a valid list or range of values for any given setting. -TODO: This may be tested by attempting to disobey specified maximums and minimums on numerical settings in a unit test +TODO: This may be tested by a unit test attempting to set a value outside a given min/max range. .. req:: Setting addition, renaming, and removal shall be supported.setting's behavior. :id: REQ_SETTINGS_CHANGES @@ -105,14 +107,6 @@ The setting package shall accomodate the introduction of new settings, renaming 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 -.. req:: The settings package shall contain a default state of all settings. - :id: REQ_SETTINGS_DEFAULTS - :status: implemented, needs more tests - -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. - .. req:: The settings package shall support version tracking. :id: REQ_SETTINGS_VERSION :status: implemented, needs more tests @@ -121,13 +115,13 @@ The input files generated by the settings system will most often exist outside o TODO: This may be tested by unit tests with out of date or omitted version information -.. req:: The settings system shall raise an error if the same setting is defined twice. +.. req:: The settings system shall raise an error if the same setting is created twice. :id: REQ_SETTINGS_DUPLICATES :status: implemented, needs more tests -When a user defines a setting twice, it shall be detected as an error which is raised to the user. +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 defined twice, and failing. +TODO: This may be tested by unit tests loading and checking settings that have a setting created twice, and failing. .. req:: ARMI shall be able to represent a user-specified reactor. :id: REQ_REACTOR @@ -203,19 +197,15 @@ TODO: This may be tested by unit tests loading and checking settings that have a :id: REQ_1 :status: needs implementation, needs test - The state shale be made available to users and modules, which may in turn modify the - state (e.g. for analysis or based on the results of a physical calculation). 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 state shale be made available to users and Plugins, which may in turn modify the state (e.g. for analysis or based on the results of a physical calculation). ARMI shall fully define how all aspects of state may be accessed and modified and shall reflect any new state after it is applied. - 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. + 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. -.. req:: The operator package shall provide a means by which to communicate inputs and results between analysis modules. +.. req:: The operator package shall provide a means by which to communicate inputs and results between analysis plugins. :id: REQ_OPERATOR_IO :status: needs implementation, needs test -The operator package shall receive output from calculation modules and store the results on a well-defined central model. A composite pattern shall be used, with a Reactor containing Assemblies containing Blocks, etc. +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. .. req:: The operator package shall provide a means to perform computations in parallel on a high performance computer. :id: REQ_OPERATOR_PARALLEL @@ -223,25 +213,25 @@ The operator package shall receive output from calculation modules and store the 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. -.. req:: The operator package shall allow physics coupling between analysis modules. +.. req:: The operator package shall allow physics coupling between analysis plugins. :id: REQ_OPERATOR_COUPLING :status: needs implementation, needs test -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 modules. +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. -.. req:: The operator package shall allow analysis modules to be replaced without affecting interfaces in other modules. +.. req:: The operator package shall allow analysis plugins to be replaced without affecting interfaces in other plugins. :id: REQ_OPERATOR_ANALYSIS :status: needs implementation, needs test -Often, a module is replaced with a new module fulfilling some new requirement. When this happens, the operator package shall isolate required changes to the new module. For example, if a fuel performance module needs temperatures but the temperature-computing module is replaced, the fuel performance module should require no changes to work with the drop-in replacement. This requires modular design and standardization in state names. +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. -.. req:: The operator package shall coordinate calls to the various modules. +.. req:: The operator package shall coordinate calls to the various plugins. :id: REQ_OPERATOR_COORD :status: needs implementation, needs test -Based on user settings, the ordering, initialization, and calls to other modules shall be coordinated by the operator package. The operator package must therefore be aware of dependencies of each module. +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. -.. req:: The latticePhysics package will execute the lattice physics code in a parallel, serial, or distributed fashion depending on the mode. +.. req:: The latticePhysics package will execute the lattice physics code in a parallel or serial fashion depending on the mode. :id: REQ_LATTICE_EXE :status: needs implementation, needs test @@ -279,7 +269,7 @@ TODO: A unit test can be used to demonstrate that all nuclide names are unique. :id: REQ_NUCDIR_LABELS :status: needs implementation, needs test -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 differen 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. +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. @@ -289,7 +279,7 @@ TODO: A unit test can be used to demonstrate that all nuclides have unique 4-cha 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. -A unit test can be used to demonstrate that lumped nuclides can be used and created. +TODO: A unit test can be used to demonstrate that lumped nuclides can be used and created. .. req:: The nucDirectory package shall allow for elemental nuclides. :id: REQ_NUCDIR_ELEMENTALS @@ -333,12 +323,12 @@ TODO: A unit test can be generated to test that the correct decay chain is prese :id: REQ_NUCDIR_TRANSMUTE :status: needs implementation, needs test -In addition to the decay chain, nuclides may transmute through interactions into other nuclides. The nucDirectory shall contain the transmutations necessary for modeling a TWR, including: +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` -- fission +- `n,\fission` - `n,\gamma` - `n,\alpha` @@ -456,7 +446,7 @@ As the report package is a lightweight interface to write data out to a text bas For performance, many physics calculations are done in parallel. The reactor must be able to synchronize the state on multiple processors efficiently. -.. req:: The nucDirectory package shall, wherever possible, the software shall prevent duplication of data to limit the memory footprint of this information. +.. req:: The nucDirectory package shall try to prevent data duplication to limit the memory footprint of this information. :id: REQ_NUCDIR_DUPLICATION :status: needs implementation, needs test @@ -467,19 +457,14 @@ TODO: Is this testable? Software Attributes ------------------- -.. req:: The database produced shall be easily accessible in a variety of operating systems. - :id: REQ_DB_OS +.. req:: ARMI shall generally support at least one modern Windows and one modern CentOS operating system version. + :id: REQ_OS :status: needs implementation, needs test .. req:: The database produced shall be easily accessible in a variety of programming environments beyond Python. :id: REQ_DB_LANGUAGE :status: needs implementation, needs test -.. req:: The report package shall be easily accessible in a variety of operating systems. - :id: REQ_REPORT_OS - :status: needs implementation, needs test - - .. req:: The settings package shall use human-readable, plain-text files as input. :id: REQ_SETTINGS_READABLE :status: implemented, needs more tests @@ -491,12 +476,6 @@ The user must be able to read and edit their settings file as plain text in broa Software Design Constraints --------------------------- -.. req:: The database package shall provide compatability with all previously generated databases. - :id: REQ_DB_BACKWARDS_COMPAT - :status: needs implementation, needs test - -With very few redesign exceptions, as qualified cases are produced for analysis and rerunning, it is imperative the data always be in an accesible form. - .. req:: The report package shall not burden new developers with grasping a complex system. :id: REQ_REPORT_TECH :status: needs implementation, needs test @@ -507,11 +486,19 @@ Given the functional requirements of the report package, new developers should b :id: REQ_REACTOR_STOCHASTIC :status: needs implementation, needs test -Given a set of input the same reactor design and run should be proceed in a fixed fashion for reproduction. +Any two ARMI runs with the same input file must produce the same results. -The nucDirectory package shall use nuclear data that is contained within the ARMI code base. That is, the data will not be retrieved from online sources. The intent here is to prevent inadvertent security risks. +.. req:: The nucDirectory package shall use nuclear data that is contained within the ARMI code base. + :id: REQ_NUCDIR_DATA + :status: needs implementation, needs test + +The nucDirectory package shall not use data data retrieved from online sources. The intent here is to prevent inadvertent security risks. -The nucDirectory package shall follow a particular naming convention. Other physics codes use the name Am-242 for the metastable state of Am-242, and use Am-242g for the ground state. +.. req:: The nucDirectory package shall follow a particular naming convention. + :id: REQ_NUCDIR_NAMING + :status: needs implementation, needs test + +Other physics codes use the name Am-242 for the metastable state of Am-242, and use Am-242g for the ground state. -------------------------- @@ -541,8 +528,7 @@ TODO: This is completed by the :doc:`Settings Report