Reconstructed Discontinuous Galerkin System Requirements Specification

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

note

This document serves as an addendum to Framework System Requirements Specification and captures information for SRS specific to the Reconstructed Discontinuous Galerkin module.

Framework System Requirements Specification

Introduction

System Purpose

The MOOSE rDG module is a library for the implementation of simulation tools that solve convection-dominated problems using the class of so-called reconstructed discontinuous Galerkin (rDG) methods. The specific rDG method implemented in this module is rDG(P0P1), which is equivalent to the second-order cell-centered finite volume method (FVM). Cell-centered FVMs are regarded as a subset of rDG methods in the case when the baseline polynomial solution in each element is a constant monomial. The FVMs are the most widely used numerical methods in areas such as computational fluid dynamics (CFD) and heat transfer, computational acoustics, and magnetohydrodynamics (MHD).

System Scope

The purpose of this software is to provide capability to MOOSE-based applications to use a second-order, cell-centered finite volume method (FVM). This module provides a systematic solution for implementing all required components in a second-order FVM such as slope reconstruction, slope limiting, numerical flux, and proper boundary conditions. Additionally, this module provides an implementation of these components for the scalar advection equation.

System Overview

System Context

The Reconstructed Discontinuous Galerkin module is command-line driven. Like MOOSE, this is typical for a high-performance software that is designed to run across several nodes of a cluster system. As such, all 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. The Reconstructed Discontinuous Galerkin module 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 the Reconstructed Discontinuous Galerkin module and other MOOSE-based applications.

System Functions

Since the Reconstructed Discontinuous Galerkin module is a command-line driven application, all functionality provided in the software is operated through the use of standard UNIX command line flags and the extendable MOOSE input file. The Reconstructed Discontinuous Galerkin module is completely extendable so individual design pages should be consulted for specific behaviors of each user-defined object.

User Characteristics

Like MOOSE, there are three kinds of users working on the Reconstructed Discontinuous Galerkin module:

Reconstructed Discontinuous Galerkin module Developers: These are the core developers of the Reconstructed Discontinuous Galerkin module. They are responsible for following and enforcing the software development standards of the module, as well as designing, implementing, and maintaining the software.
Developers: A scientist or engineer that uses the Reconstructed Discontinuous Galerkin module alongside MOOSE to build their own application. This user will typically have a background in modeling or simulation techniques (and perhaps numerical analysis) but may only have a limited skillset when it comes to code development using the C++ language. This is the primary focus group of the module. In many cases, these developers will be encouraged to contribute module-appropriate code back to the Reconstructed Discontinuous Galerkin module, or to MOOSE itself.
Analysts: These are users that will run the code and perform analysis 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 input file format.

Assumptions and Dependencies

The Reconstructed Discontinuous Galerkin module is developed using MOOSE and can itself be based on various MOOSE modules, as such the SRS for the Reconstructed Discontinuous Galerkin module is dependent upon the files listed at the beginning of this document. Any further assumptions or dependencies are outlined in the remainder of this section.

The Reconstructed Discontinuous Galerkin module is designed with the fewest possible constraints on hardware and software. For more context on this point, the Reconstructed Discontinuous Galerkin module SRS defers to the framework Assumptions and Dependencies. Any physics-based or mathematics-based assumptions in code simulations and code objects are highlighted in their respective documentation pages.

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
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
SRS	Software Requirement Specification

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

rdg: Auxkernels
10.1.1The system shall be able compute a component of the negative gradient of a variable.

rdg: Benchmarking
10.2.1
The system shall be capable of solving an ion wall loss problem, as described in chapter 1, pages 26-27 of Principles of Plasma Discharge and Material Processing (ISBN 0-471-72001-1), and reproduce the same
1. field variable results, and
2. kinetic particle results.

rdg: Kernels
10.3.1The system shall be able to solve a simple diffusion problem.

rdg: Raybcs
10.4.1
The system shall be capable of reflecting computational particles off of boundaries and maintain consistent velocity data
1. in a 1D domain
2. in a 2D domain
3. in a 3D domain

rdg: Userobjects
10.5.1
The system shall support placing particles within a bounding box uniformly in a parallel consistent manner in the element type
1. EDGE2
2. TRI3
3. QUAD4
4. HEX8
5. TET4
6. PYRAMID5
7. PRISM6
10.5.2
The system return a useful error when the user
1. requests an element type that initialization has not been verified for
2. tries to setup a bounding box where a component of bottom_left is greater than top_right
10.5.3
The system return a useful warning to remind the user that the
1. 2 extra components of the bottom_left and top_right inputs are ignored in 1D simulations
2. 1 extra component of the bottom_left and top_right inputs are ignored in 2D simulations
10.5.4
The system shall be capable of placing particles inside of EDGE2 elements uniformly
1. and solve an electrostatic potential based on the particle positions
2. in a parallel consistent manner
3. and compute the error between an exact electrostatic potential and the finite element solution
10.5.5
The system shall be capable of placing particles inside of QUAD4 elements uniformly
1. and solve an electrostatic potential based on the particle positions
2. in a parallel consistent manner
3. and compute the error between an exact electrostatic potential and the finite element solution
10.5.6
The system shall be capable of placing particles inside of TRI3 elements uniformly
1. and solve an electrostatic potential based on the particle positions
2. in a parallel consistent manner
3. and compute the error between an exact electrostatic potential and the finite element solution
10.5.7
The system shall be capable of placing particles inside of HEX8 elements uniformly
1. and solve an electrostatic potential based on the particle positions
2. in a parallel consistent manner
3. and compute the error between an exact electrostatic potential and the finite element solution
10.5.8
The system shall be capable of placing particles inside of PRISM6 elements uniformly
1. and solve an electrostatic potential based on the particle positions
2. in a parallel consistent manner
3. and compute the error between an exact electrostatic potential and the finite element solution
10.5.9
The system shall be capable of placing particles inside of PYRAMID5 elements uniformly
1. and solve an electrostatic potential based on the particle positions
2. in a parallel consistent manner
3. and compute the error between an exact electrostatic potential and the finite element solution
10.5.10
The system shall be capable of placing particles inside of TET4 elements uniformly
1. and solve an electrostatic potential based on the particle positions
2. in a parallel consistent manner
3. and compute the error between an exact electrostatic potential and the finite element solution
10.5.11
The system return a useful error when the user
1. requests an element type that initialization has not been verified for
2. tries to give particles zero mass
3. tries to give particles a negative mass
4. does not provide enough distributions to sample for velocity initialization.
5. tries to put 0 particles in each element.
6. tries to request that a particle type be initialized with zero number density
7. tries to request that a particle type be initialized with a negative number density
10.5.12
The system shall be capable of placing particles on a uniform grid on the mesh
1. in one dimension.
10.5.13
The system shall return a useful error when the user tries to use the UniformGridParticleInitializer in
1. a two-dimensional simulation, and
2. a three-dimensional simulation.
10.5.14
The system shall be capable of contributing to the residual of a variable based on the computational particles'
1. charge density, and
2. number density.
10.5.15The system shall be capable of accurately capturing the path of charged particles in both an electric and a magnetic field
10.5.16The system shall be capable of accurately capturing the path of charged particles in a perpendicular magnetic field
10.5.17The system shall be capable of applying a linear impluse from a force field perpendicular to a particles initial velocity using the boris stepper when there is 0 magnetic field
10.5.18The system shall be capable of applying a linear impluse from a force field parallel to a particles velocity using the boris stepper when there is 0 magnetic field
10.5.19
The system shall report a reasonable error from the particle stepper when
1. the user does not provide 3 components of the electric field
2. the user does not provide 3 components of the magnetic field
10.5.20The system shall be capable of applying a linear impulse from a force field perpendicular to a particle\'s initial velocity
10.5.21The system shall be capable of applying a linear impulse from a force field parallel to a particle's velocity
10.5.22
The system shall report a reasonable error from the particle stepper when
1. the user does not provide 3 components of the force field
10.5.23The system shall be capable of tracking 3 velocity components within the PIC capability while propagating rays in lower dimensions

rdg: Utils
10.6.1The system shall support the accumulation of point values as if they were point sources into an auxiliary field
10.6.2The system shall report a reasonable error when accumulating point values into an auxiliary field when the system is not properly finalized
10.6.3The system shall support mapping data from rays to an aux variable and reset the aux variable to 0 on each time step
10.6.4The system shall support mapping data from rays to an aux variable and reset the aux variable to 0 on each time step on a 2 dimensional mesh
10.6.5The system shall support mapping data from rays to an aux variable and then solve differential equations based on the data mapped from rays
10.6.6The system shall support the accumulation of point values as if they were point sources into a nonlinear field
10.6.7The system shall allow a ray to sample the value of field variable at any point in space as it moves through space

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

The Reconstructed Discontinuous Galerkin module is command line driven and conforms to all standard terminal behaviors. Specific human system interaction accommodations shall be a function of the end-user's terminal. MOOSE (and therefore the Reconstructed Discontinuous Galerkin module) does support optional coloring within the terminal's ability to display color, which may be disabled.

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 software in its entirety will be made available under the terms of a designated software license. These license terms are outlined in the LICENSE file alongside the Reconstructed Discontinuous Galerkin module source code. As a MOOSE physics module, the license for the Reconstructed Discontinuous Galerkin module is identical to that of the framework - that is, the LGPL version 2.1 license.

Reliability

The regression test suite will cover at least 65% of all lines of code within the Reconstructed Discontinuous Galerkin module at all times. Known regressions will be recorded and tracked (see Maintainability) to an independent and satisfactory resolution.

System Modes and States

MOOSE applications normally run in normal execution mode when an input file is supplied. However, there are a few other modes that can be triggered with various command line flags as indicated here:

Command Line Flag	Description of mode
`-i <input_file>`	Normal execution mode
`--split-mesh <splits>`	Read the mesh block splitting the mesh into two or more pieces for use in a subsequent run
`--use-split`	(implies -i flag) Execute the simulation but use pre-split mesh files instead of the mesh from the input file
`--yaml`	Output all object descriptions and available parameters in YAML format
`--json`	Output all object descriptions and available parameters in JSON format
`--syntax`	Output all registered syntax
`--registry`	Output all known objects and actions
`--registry-hit`	Output all known objects and actions in HIT format
`--mesh-only` (implies -i flag)	Run only the mesh related tasks and output the final mesh that would be used for the simulation
`--start-in-debugger <debugger>`	Start the simulation attached to the supplied debugger

note

The list of system-modes may not be extensive as the system is designed to be extendable to end-user applications. The complete list of command line options for applications can be obtained by running the executable with zero arguments. See the command line usage.

Physical Characteristics

The Reconstructed Discontinuous Galerkin module is software only with no associated physical media. See System Requirements for a description of the minimum required hardware necessary for running the Reconstructed Discontinuous Galerkin module.

Environmental Conditions

Not Applicable

System Security

MOOSE-based applications such as the Reconstructed Discontinuous Galerkin module have no requirements or special needs related to system security. The software is designed to run completely in user-space with no elevated privileges required nor recommended.

Information Management

The core framework and all modules in their 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

MOOSE-based applications 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. The Reconstructed Discontinuous Galerkin module development team follows the NQA-1 standards.

Packaging, Handling, Shipping and Transportation

No special requirements are needed for packaging or shipping any media containing MOOSE and Reconstructed Discontinuous Galerkin module source code. However, some MOOSE-based applications that use the Reconstructed Discontinuous Galerkin module 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 analytical solutions, the method of manufactured solutions, and convergence rate analysis.

Introduction
System Overview
References
Definitions and Acronyms
System Requirements
Verification