Electromagnetics 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 Electromagnetics module.

Framework System Requirements Specification

Introduction

System Purpose

The MOOSE Electromagnetics module provides an interface to and library containing Maxwell's equations within the MOOSE application ecosystem. It is intended to be used as either a standalone simulation code for electrodynamics or coupled to other MOOSE ecosystem codes (including MOOSE-wrapped applications). Thus, the Electromagnetics module uses the same object-oriented design as MOOSE in order to make simulation design and new development straightforward for engineers and researchers.

System Scope

The scope of the Electromagnetics module is to provide a set of interfaces and objects for building electrodynamics simulations based on the finite element method (FEM). Regarding solvers, meshing libraries, as well as solution/coupling methods and interfaces, the Electromagnetics module relies on the infrastructure provided by the MOOSE framework.

The system contains, generally, a base set of kernels, boundary conditions, and interface conditions designed for the solution of vector fields derived from Maxwell's equations. Further, it currently contains more specific capability in the following general areas:

Wave reflection, transmission, and absorption
Electrostatic contact on electrically imperfect surfaces

Electromagnetics module developers work with framework and other module and application developers to ensure that the Electromagnetics module provides adequate capability to support on-going and prospective research opportunities involving aspects of electromagnetics.

System Overview

System Context

The Electromagnetics 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 Electromagnetics 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 Electromagnetics module and other MOOSE-based applications.

System Functions

Since the Electromagnetics 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 Electromagnetics 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 Electromagnetics module:

Electromagnetics module Developers: These are the core developers of the Electromagnetics 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 Electromagnetics 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 Electromagnetics 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 Electromagnetics module is developed using MOOSE and can itself be based on various MOOSE modules, as such the SRS for the Electromagnetics 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 Electromagnetics module is designed with the fewest possible constraints on hardware and software. For more context on this point, the Electromagnetics module SRS defers to the framework Assumptions and Dependencies. Any physics-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:

GCC/Clang C++17 compliant compiler (GCC @ 7.5.0, Clang @ 10.0.1 or greater)
- Note: Intel compilers are not supported.
Memory: 8 GBs of RAM for optimized compilation (16 GBs for debug compilation), 2 GB per core execution
Processor: 64-bit x86 or ARM64 (specifically, Apple Silicon)
Disk: 30GB
A POSIX compliant Unix-like operating system, including the two most recent versions of MacOS and most current versions of Linux.
Git version control system
Python @ 3.7 or greater

Functional Requirements

electromagnetics: Auxkernels
4.1.1The system shall calculate the current density provided with electrostatic field calculations, using an AD material property for electrical conductivity.
4.1.2The system shall calculate the current density provided with electrostatic field calculations, using a non-AD material property for electrical conductivity.
4.1.3The system shall calculate the current density when provided with a vector field variable, simulating the case when an electromagnetic vector field is provided.
4.1.4
The system shall provide an error while
1. calculating the current density when both electrostatic and electromagnetic field variables are provided by the user.
2. calculating the current density when an electrostatic calculation is requested but an electromagnetic field variable is provided.
3. calculating the current density when an electromagnetic calculation is requested but an electrostatic field variable is provided.

electromagnetics: Bcs
4.2.1The system shall be able to simulate the field result of an incoming wave reflected on a biased surface and properly absorb the reflected wave in a boundary condition.
4.2.2The system shall be able to simulate a first order electromagnetic wave launching/absorbing port as a boundary condition, given the incoming/outgoing wave, for real and imaginary components of the field and for vector variables.
4.2.3The system shall use the correct jacobian contribution for a first order electromagnetics wave launching/absorbing port boundary condition for vector field variables.
4.2.4The system shall present an error to the user whenever the mode of operation for VectorEMRobinBC is set to absorbing, but incoming wave information is supplied.

electromagnetics: Benchmarks
4.3.1The system shall calculate the static far field pattern of a half-wave dipole antenna.
4.3.2The system shall calculate the transient far field pattern of a half-wave dipole antenna.
4.3.3The system shall calculate the fundamental waveguide cutoff wavenumber for a TM mode for a rectangular waveguide geometry.
4.3.4The system shall calculate the fundamental waveguide cutoff wavenumber for a TM mode for a circular waveguide geometry.
4.3.5The system shall calculate the fundamental waveguide cutoff wavenumber for a TM mode for a coaxial waveguide geometry.
4.3.6The system shall calculate the evanescent wave decay for a waveguide structure below the cutoff frequency.
4.3.7The system shall calculate the reflection of a 1D electric field plane wave in a metal backed dielectric slab.
4.3.8The system shall be able to simulate a 2D electric field waveguide with boundary conditions for wave launching, absorption, and conducting walls for scalar field variables.
4.3.9The system shall present an error to the user whenever the mode of operation for EMRobinBC is set to absorbing, but incoming wave information is supplied.

electromagnetics: InterfaceKernel Objects
4.4.1The system shall calculate the appropriate parallel component equivalence interface condition dictated by Maxwell's Equations for parallel electromangetic vector fields.
4.4.2The system shall calculate the appropriate perpendicular equivalence interface condition dictated by Maxwell's Equations for perpendicular electromagnetic vector fields, when properties are identical on either side of the interface.
4.4.3The system shall calculate the appropriate equivalence interface condition dictated by Maxwell's Equations for both perpendicular and parallel components of electromagnetic vector fields at the same time with default, identical material property parameters.
4.4.4The system shall calculate the appropriate interface condition dictated by Maxwell's Equations for both perpendicular (subject to material properties) and parallel (equivalent) components of electromagnetic vector fields at an interface at the same time, with user-supplied material property parameters and zero free charge.
4.4.5The system shall calculate the appropriate interface condition dictated by Maxwell's Equations for both perpendicular (subject to material properties) and parallel (equivalent) components of electromagnetic vector fields at an interface at the same time, with user-supplied material property and free charge parameters.
4.4.6The system shall be capable of calculating the effect of electrostatic contact at an interface between two different materials, given a user-supplied contact conductance.
4.4.7The system shall calculate the correct AD jacobian contribution for electrostatic contact at an interface, given a user-supplied contact conductance.
4.4.8The system shall supply an error if both user-supplied and system-calculated contact conductance is requested when determining the effect of electrostatic contact on an interface.
4.4.9The system shall be capable of calculating the effect of electrostatic contact at an interface between two different materials, given a system-calculated contact conductance.
4.4.10The system shall calculate the correct AD jacobian contribution for electrostatic contact at an interface, given a system-calculated contact conductance.
4.4.11The system shall calculate the correct electrostatic contact potential solution when compared to an analytic result, given a one-dimensional, two-material-block scenario.
4.4.12The system shall calculate the correct electrostatic contact potential solution when compared to an analytic result, given a one-dimensional, three-material-block scenario.

electromagnetics: Kernels
4.5.1The system shall be capable of modeling the Helmholtz equation for scalar complex field variables, where real/imaginary coupling occurs for both the diffusion and reaction terms and coefficient values vary spatially.
4.5.2The system shall be capable of modeling the vector Helmholtz equation for vector fields.
4.5.3The system shall be capable of modeling the vector Helmholtz equation for vector fields with a vector current density source for real and imaginary components.

electromagnetics: Postprocessors
4.6.1The system shall supply an error if the ReflectionCoefficient object is used on meshes with a dimension larger than one.

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 Electromagnetics 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 Electromagnetics 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 Electromagnetics module source code. As a MOOSE physics module, the license for the Electromagnetics 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 95% of all lines of code within the Electromagnetics 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 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 Electromagnetics module is software only with no associated physical media. See System Requirements for a description of the minimum required hardware necessary for running the Electromagnetics module.

Environmental Conditions

Not Applicable

System Security

MOOSE-based applications such as the Electromagnetics 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 Electromagnetics 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 Electromagnetics module source code. However, some MOOSE-based applications that use the Electromagnetics 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