MOOSE Tools System Requirements Specification

This template follows INL template TEM-135, "IT System Requirements Specification".

Introduction

System Purpose

MOOSE Tools is a set of Python utilities designed to support the MOOSE framework. MOOSE Tools contains two main utilities – MOOSE Documentation System (MooseDocs) and TestHarness – that facilitate MOOSE documentation (e.g., website and presentation building) and code testing. While tied to the framework most directly (and housed within the MOOSE code repository), MOOSE Tools can be used in a more general sense to support other codes. More specific information on the design and structure of MOOSE Tools utilities can be found on the main documentation page.

The design goal of MOOSE Tools is to give code developers access to common tools and resources to help them verify, test, and document their code and simulations, as well as make best use of the input and output data obtained in the process of performing research. To this end, many of the Tools utilities are extensible and flexible, like MOOSE itself, and therefore are designed to be expanded and reconfigured to meet the needs of the end-user.

System Scope

The scope of MOOSE Tools is to provide a set of utilities to support MOOSE development. Namely, verification, testing, documentation, and data analysis and manipulation of MOOSE code and I/O. Tools code is written in a general way, so that it can be extended and tuned to the needs of the user/developer. The major two systems of the Tools utilities are described in the following sections, but more information on the support utilities also contained within MOOSE tools can be found on the main documentation page.

MooseDocs

The MOOSE Documentation System (MooseDocs) facilitates documentation of the MOOSE and MOOSE Tools code bases, as well as supports the MOOSE SQA practices. It contains many extensions for website rendering, navigation, linking, bibliographic references, and support for integration of code and input file snippets (among many more features), as well as capabilities for development of training and presentation slides and reports.

TestHarness

The TestHarness system is responsible for finding tests and running them. The extended philosophy behind MOOSE testing can be found in the MOOSE Test System documentation page, and this philosophy has driven the creation and design choices of the TestHarness system.

Within MOOSE there are three different testing ideas:

The "tests": which are typically "Regression Tests" consisting of input files and known good outputs ("gold" files).
Unit tests that test the functionality of small separable pieces
The TestHarness: a piece of software that was written to _run_ tests and aggregate the results.

The TestHarness integrates with the MOOSE CI and CD workflows to facilitate testing across multiple operating systems and hardware architectures.

System Overview

System Context

MOOSE Tools utilities are command-line driven applications. This is typical for high-performance software that is designed to run across several nodes of a cluster system. As such, all of the usage of the software is through any standard terminal program generally available on all supported operating systems. Similarly, for the purpose of interacting through the software, there is only a single user, "the user", which interacts with the software through the command-line. MOOSE Tools does not maintain any back-end database or interact with any system daemons. It is an executable, which may be launched from the command line and writes out various result files as it runs.

Figure 1: Usage of MOOSE and MOOSE-based applications. MOOSE Tools usage is similar.

System Functions

Since MOOSE Tools is a command-line driven application, all functionality provided in the provided set of utilities is operated through the use of standard UNIX command line flags, YAML configuration files, Python-based scripts, and user-created MOOSE Markdown Specification (MooseDown). Many of the MOOSE Tools utilities are completely extendable so individual design pages should be consulted for specific behaviors of each system and extension.

User Characteristics

MOOSE Tools Developers: These are the core developers of the project. They will be responsible for following and enforcing the appropriate software development standards. They will be responsible for designing, implementing and maintaining the software.
Developers: A Scientist or Engineer that utilizes MOOSE Tools to build their own tools, extensions, or scripts to assist in the development of a project - either MOOSE or MOOSE-based applications or custom code to which MOOSE Tools has been adapted. This user will typically have a background in modeling and simulation techniques and/or numerical analysis but may only have a limited skill-set when it comes to the Python language. This is our primary focus group. In many cases these developers will be encouraged to give their code back to the MOOSE Tools maintainers.
Analysts: These are users that will run the code and perform various analysis and testing on the simulations they perform. These users may interact with developers of the system requesting new features and reporting bugs found and will typically make heavy use of the pre-built scripts, configuration files, and the MooseDown file format.

Assumptions and Dependencies

This section outlines any assumptions and/or dependencies of the software.

The software should be designed with the fewest possible constraints. Ideally the software should run on a wide variety of evolving hardware so it should follow well-adopted standards and guidelines. The software should run on any POSIX compliant system containing the Python language and interpreter. The main interface for the software will be command line based with no assumptions requiring advanced terminal capabilities such as coloring and line control.

References

ISO/IEC/IEEE 24765:2010(E). Systems and software engineering—Vocabulary. first edition, December 15 2010.

@manual{ISO-systems-software,
    author = "24765:2010(E), ISO/IEC/IEEE",
    title = "Systems and software engineering---Vocabulary",
    edition = "First",
    year = "2010",
    month = "December 15"
}

ASME NQA-1. ASME NQA-1-2008 with the NQA-1a-2009 addenda: Quality Assurance Requirements for Nuclear Facility Applications. first edition, August 31 2009.

@manual{ASME-NQA-1-2008,
    author = "NQA-1, ASME",
    title = "ASME NQA-1-2008 with the NQA-1a-2009 addenda: Quality Assurance Requirements for Nuclear Facility Applications",
    orginization = "American Socieity of Mechanical Engineers",
    year = "2009",
    month = "August 31",
    edition = "First"
}

Definitions and Acronyms

This section defines, or provides the definition of, all terms and acronyms required to properly understand this specification.

Definitions

Verification: (1) The process of: evaluating a system or component to determine whether the products of a given development phase satisfy the conditions imposed at the start of that phase. (2) Formal proof of program correctness (e.g., requirements, design, implementation reviews, system tests) (24765:2010(E), 2010).

Acronyms

Acronym	Description
CD	continuous deployment
CI	continuous integration
I/O	Input/Output
INL	Idaho National Laboratory
LGPL	GNU Lesser General Public License
MOOSE	Multiphysics Object Oriented Simulation Environment
NQA-1	Nuclear Quality Assurance Level 1
POSIX	Portable Operating System Interface
SQA	Software Quality Assurance

System Requirements

In general, the following is required for MOOSE-based development:

A POSIX compliant Unix-like operating system. This includes any modern Linux-based operating system (e.g., Ubuntu, Fedora, Rocky, etc.), or a Macintosh machine running either of the last two MacOS releases.

Hardware	Information
CPU Architecture	x86_64, ARM (Apple Silicon)
Memory	8 GB (16 GBs for debug compilation)
Disk Space	30GB

Libraries	Version / Information
GCC	9.0.0 - 12.2.1
LLVM/Clang	10.0.1 - 19
Intel (ICC/ICX)	Not supported at this time
Python	3.10 - 3.13
Python Packages	packaging pyaml jinja2

Functional Requirements

python: Test
2.1.1The system shall include a tool for creating spatial convergence plots using method of manufactured solutions.
2.1.2The system shall include a tool for writing spatial convergence data to a file using method of manufactured solutions.
2.1.3The system shall include a tool for creating temporal convergence plots using method of manufactured solutions.
2.1.4The system shall include a tool for writing temporal convergence data to a file using method of manufactured solutions.
2.1.5The system shall include a tool to output solution and forcing functions.
2.1.6The system shall include a tool for computing forcing functions for the method of manufactured solutions.
2.1.7The system shall include a TokenComponent and RenderComponent objects for creating MooseDocs extensions.
2.1.8The system shall include lexer object capable of recursively processing text.
2.1.9The system shall include a reader object for reading files.
2.1.10The system shall include a translator for converting documentation formats.
2.1.12The system shall include a utility for generating documentation stub pages.
2.1.13The system shall include a utility for displaying the application syntax tree.
2.1.14The system shall include a utility for converting markdown documentation to other formats.
2.1.15The system shall include a utility to initialize documentation items.
2.1.16The system shall have a storage structure for holding ordered items by name.
2.1.17The system shall include utility for parsing key, value pairs from a string.
2.1.18The system shall include special exceptions for use during tokenization and rendering.
2.1.19The system shall include a utility for creating text boxes suitable for terminal output.
2.1.20The system shall include mixin classes for creating objects that require configuration data, translator objects, or component objects.
2.1.21The system shall include the ability to load extensions dynamically.
2.1.22The system shall include a YAML based configuration.
2.1.23The system shall include a database object for storing information regarding source files.
2.1.24The system shall include the ability to build a file tree from markdown files.
2.1.25The system shall include a utility for locating filenames using a fuzzy search.
2.1.26The system shall include a utility to locate a filename using a fuzzy search and error if none or multiple are located.
2.1.27The system shall include a utility to conditionally add dependencies to output of documentation based on the existence of certain content.
2.1.28
The system shall include documentation tools that provide support for
1. markdown-like syntax,
2. special characters,
3. comments within markdown syntax,
4. acronyms within markdown syntax,
5. building software quality documents,
6. automatically cross-linking files,
7. linking to continuous integration testing results,
8. listing and linking to content within and across documents,
9. automatically retrieving application syntax,
10. creating alert text boxes,
11. displaying images and videos,
12. creating source code listings,
13. displaying image galleries,
14. template files,
15. creating syntax examples,
16. conditional operations,
17. automatically retrieving python syntax,
18. create modal website content,
19. support equations,
20. displaying algorithmic pseudo-code,
21. include date/time operations,
22. include git repository information,
23. support documentation tags for filtering, and
24. reporting versions of systematically tracked packages.
2.1.29The system shall include a test that ensures that all python files within the tests directories have an associated test specification.
2.1.30The system shall be able to successfully translate the standalone form of the subsite test configuration by using the default build command.
2.1.31
The system shall be able to use each of the available Executioner types (serial, queue-based parallel, barrier-based parallel, and pipe-based parallel schemes) to translate markdown syntax to:
1. HTML;
2. HTML with Materialize support; and
3. LaTeX.
2.1.32
The system shall be able to successfully translate multiple configurations by using the build command with the --config option such that
1. the build routines for the main test site precede those of the subsite, as well as
2. in the reverse order but with the --fast option added for testing efficiency.
2.1.33The system shall include a tree node object with arbitrary property creation.
2.1.34The system shall include tree object suitable for abstract syntax trees.
2.1.35The system shall include tree object suitable for HTML.
2.1.36The system shall include tree object suitable for latex.
2.1.37The system shall include tree object suitable for file structures.
2.1.38The system shall include data structures for reporting requirement information.
2.1.39The system shall include a tool for checking application syntax for software quality documentation.
2.1.40The system shall include a tool for gathering requirement information for software quality documentation.
2.1.41The system shall include a tool for testing requirement information for software quality documentation.
2.1.42The system shall have reporting tools for software quality.
2.1.43
The system shall have tools for reporting software quality status that includes reports for monitoring
1. files and websites;
2. tests and requirements; and
3. design content.
2.1.44The system shall include a tool for gathering multiple software quality reports.
2.1.45The system shall include a utility to enable the recording of logging messages without display.
2.1.46The system shall include a utility to enable control the of logging messages for software quality reports.
2.1.47The system shall include documented requirement collections and SQA template files.
2.1.48The system shall include the necessary components for building a syntax tree from application information.
2.1.49The system shall include a utility for generating a complete syntax tree from an application executable.

python: Tests
2.2.1
The system shall include a utility for building tree structures using a scripting language that includes
1. a node object,
2. a tree iteration function, and
3. search algorithms.
2.2.2The system shall contain python utilities that include a messaging interface.
2.2.3The system shall contain python utilities that include a messaging interface capable of creating a dialog window.
2.2.4The system shall contain python utilities for reading CSV data via pandas.DataFrame.
2.2.5The system shall contain python utilities for reading postprocessor data.
2.2.6The system shall contain python utilities for reading vector postprocessor data.
2.2.7The system shall contain python utilities for reading reporter data.
2.2.8The system shall contain python utilities for converting camel case text to underscore separated text.
2.2.9The system shall contain python utilities for reading YAML files.
2.2.10The system shall contain python utilities for breaking a list of items into a specified number of chunks.
2.2.11The system shall include a utility for locating a MOOSE-based application executable.
2.2.12The system shall include utilities for executing version control system commands.
2.2.13The system shall include a utility running an executable.
2.2.14The system shall include a tool for accessing CIVET testing results.
2.2.15The system shall contain python utilities for reading PerfGraphReporter data.
2.2.16The system shall contain python utilities for reading compared csv files.
2.2.17The system shall contain a python postprocessor class to combine CSV files together.
2.2.18The system shall contain a python utility for parsing hierarchical input text (HIT) files.
2.2.19The system shall contain a python utility for tokenizing hierarchical input text (HIT) files.
2.2.20The system shall include examples for reading, writing, and manipulating input file syntax using python.
2.2.21The system shall report a non-failing status after a predetermined time of no activity
2.2.22The system shall support the output of the longest running jobs
2.2.26The system shall support the output of single-lined test results with a user configurable format string
2.2.27The system shall restrict tests based on the available dual number derivative vector size
2.2.29The system shall not perform a test if said test has a skipped dependency
2.2.33The system shall report deleted tests as failures when specified with additional –extra-info optionsIn all other cases, deleted tests will be treated as skipped tests
2.2.34The system shall perform all operations required of the TestHarness except executing a test
2.2.35The system shall run only tests designated with display_required.
2.2.36The system shall allow users to ignore and override specified prerequisites
2.2.40The system shall skip a test if required application is unavailable
2.2.41The system shall only perform the validation of test results without executing the test itself
2.2.42The system shall skip syntax only tests if instructed to do so
2.2.43The system shall properly run tests using distributed mesh options
2.2.44The system shall supply the necessary resources a test requires, and report when these resources are insufficient to run said test
2.2.45The system shall print all caveats pertaining to the test involved
2.2.47The system shall perform normal operating procedures on a single provided test spec file
2.2.48The system shall write the output (stdout|stderr) that an executed test generated to a file as designated by user supplied arguments
2.2.49The system shall be able to perform recovery of a test
2.2.50The system shall trim output once threshold has exceeded
2.2.51The system shall detect and report race conditions that exist in the supplied tests
2.2.52The system shall detect and report unreadable output in executed commands
2.2.53The system shall run only tests which previously have failed
2.2.54The system shall support restrictions based on the python version available.
2.2.55The system shall be able to compare computed values against measured data using mean value and standard deviation
2.2.56The system shall be able to run tests in relative path directories supplied by the spec file
2.2.58The system shall perform a test after all other tests have passed if specified to do so
2.2.60The system shall be able to replay last results
2.2.61The system shall be able to evaluate a given test with a user-supplied evaluation function.
2.2.62The system shall skip tests not capable of being run depending on binary installation type
2.2.63The system shall skip tests not capable of being run depending on micro architecture
2.2.64The system shall not skip non-heavy tests for which heavy tests depend on
2.2.65The system shall provide a common interface for storing and retrieving output that supports sanitization issues =
2.2.66The system shall test the functionality of the TestHarness.getExecutable method.
2.2.67The system shall support systematically capturing performance statistics from the execution of MOOSE application tests.
2.2.68The system shall provide an interface for storing results and data for validation cases
2.2.69The system shall support storing results and data for validation cases that are combined with a standard test
2.2.70The system shall provide a python interface for interacting with previous test results stored in a database
2.2.71The system shall provide a python interface for loading previous test results from a database

Usability Requirements

No requirements of this type exist for this application, beyond those of its dependencies.

Performance Requirements

No requirements of this type exist for this application, beyond those of its dependencies.

System Interfaces

No requirements of this type exist for this application, beyond those of its dependencies.

System Operations

Human System Integration Requirements

MOOSE Tools contains command line driven applications which conform to all standard terminal behaviors. Specific human system interaction accommodations shall be a function of the end-user's terminal. Optional accommodations will be outlined in utility design documents.

Maintainability

The latest working version (defined as the version that passes all tests in the current regression test suite) shall be publicly available at all times through the repository host provider.
Flaws identified in the system shall be reported and tracked in a ticket or issue based system. The technical lead will determine the severity and priority of all reported issues and assign resources at their discretion to resolve identified issues.
The software maintainers will entertain all proposed changes to the system in a timely manner (within two business days).
The core framework in its entirety will be made publicly available under the LGPL version 2.0 license.

Reliability

The regression test suite will cover a sufficient amount of MOOSE Tools code such that core utility functionality is maintained at all times. Known regressions will be recorded and tracked (see Maintainability) to an independent and satisfactory resolution.

System Modes and States

MOOSE Tools utilities are typically used within other scripts or codes to facilitate particular functionality. Some, like the MOOSE Documentation System (MooseDocs) take command line arguments and run in normal execution mode when a configuration file is supplied. However, due to the nature of MOOSE Tools being a collection of utilities, each of them have their own modes and states of operation. Thus, the best resource is their design and operation documentation, which can be shown below in Table 1.

Table 1:

Tool	Description
TestHarness	Tool testing that applications work correctly as code is developed.
Memory Logger	Tool for gathering memory usage of a running process.
CSVDiff Tool	Tool for computing differences between comma separated value (CSV) files.
Method of Manufactured Solutions (MMS)	Utilities for verifying solves with the method of manufactured solutions.
free_energy.py	Tool for extracting MOOSE parsed function expressions from thermodynamic database files.
moosetree	Tool for building and searching tree structures.
pyhit	Tool for reading, writing, and manipulating MOOSE input files.
Combine CSV	Tool for combining CSV files together.
MOOSE SQA Tools	Tools for managing SQA documentation.
ReporterReader	Tool for reading JSON output of Reporter data
Module Hash Tool	Tool for generating a hash suffix for our contribution modules.
MOOSE Documentation System (MooseDocs)	Tool for creating documentation.
MooseControl	Tool for interacting with a WebServerControl

Physical Characteristics

MOOSE Tools is software only with no associated physical media. See System Requirements for a description of the minimum required hardware necessary for running a MOOSE Tools (as well as a MOOSE-based application).

Environmental Conditions

Not Applicable

System Security

MOOSE Tools utilities have no requirements or special needs related to system security. They are designed to run completely in user-space with no elevated privileges required or recommended.

Information Management

MOOSE Tools in its entirety will be made publicly available on an appropriate repository hosting site. Day-to-day backups and security services will be provided by the hosting service. More information about MOOSE backups of the public repository on INL-hosted services can be found on the following page: GitHub Backups

Polices and Regulations

As MOOSE Tools is housed within and alongside MOOSE and MOOSE-based applications, it must comply with all export control restrictions.

System Life Cycle Sustainment

MOOSE-based development follows various agile methods. The system is continuously built and deployed in a piecemeal fashion since objects within the system are more or less independent. Every new object requires a test, which in turn requires an associated requirement and design description. Some MOOSE-based development teams follow the NQA-1 standards.

Packaging, Handling, Shipping and Transportation

No special requirements are needed for packaging or shipping any media containing MOOSE source code. However, some MOOSE-based applications may be export-controlled, in which case all export control restrictions must be adhered to when packaging and shipping media.

Verification

The regression test suite will employ several verification tests using comparison against known solutions or code output.

Introduction
System Overview
References
Definitions and Acronyms
System Requirements
Verification