Electromagnetics System Design Description

This template follows INL template TEM-140, "IT System Design Description."

commentnote

This document serves as an addendum to Framework System Design Description and captures information for SDD specific to the Electromagnetics module.

Introduction

The MOOSE Electromagnetics module is based on the MOOSE framework, thus it inherits the unique features and base characteristics of the framework, as outlined in the Framework System Design Description. Specific details unique to the module are outlined in this document.

System Purpose

The Software Design Description provided here is description of each object in the system. The pluggable architecture of the underlying framework of the Electromagnetics module makes MOOSE and MOOSE-based applications straightforward to develop as each piece of end-user (developer) code that goes into the system follows a well-defined interface for the underlying systems that those object plug into. These descriptions are provided through developer-supplied "markdown" files that are required for all new objects that are developed as part of the Electromagnetics module. More information about the design documentation for MOOSE-based applications and like the Electromagnetics module can be found in Documenting MOOSE.

System Scope

The purpose of this software is to augment the core MOOSE framework to provide libraries and capability related to solving Maxwell's equations and other concepts of electrodynamics using the FEM. Scope items specific to the framework that are therefore components of the Electromagnetics module are given in the framework System Scope. A brief overview of the main components of the Electromagnetics module that exist beyond those of the framework are listed here:

ComponentDescription
Electromagnetics module libraryThe optional physics library that may be used in an application to provide electrodynamics capability
benchmarksA set of complete examples (within the module "test/tests" directory) demonstrating the use of the Electromagnetics module as well as verifying physical capabilities
unitAn application for unit testing individual Electromagnetics module classes or methods of C++ code specific to the module

Dependencies and Limitations

The Electromagnetics module, having its base on the MOOSE framework, inherits MOOSE's software dependencies. The scope of the module is evolving constantly based on funding, resources, priorities, and laboratory direction. However, like MOOSE, features and bugs can be offloaded to developers with appropriate levels of domain knowledge and direction from the module design team. The primary list of software dependencies can be found in the framework Dependencies and Limitations, as it is identical to that of MOOSE. There are currently no additional required software dependencies for using electromagnetics module code and models.

Definitions and Acronyms

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

Definitions

  • Pull (Merge) Request: A proposed change to the software (e.g. usually a code change, but may also include documentation, requirements, design, and/or testing).

  • Baseline: A specification or product (e.g., project plan, maintenance and operations (M&O) plan, requirements, or design) that has been formally reviewed and agreed upon, that thereafter serves as the basis for use and further development, and that can be changed only by using an approved change control process (NQA-1, 2009).

  • Validation: Confirmation, through the provision of objective evidence (e.g., acceptance test), that the requirements for a specific intended use or application have been fulfilled (24765:2010(E), 2010).

  • 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

AcronymDescription
APIApplication Programming Interface
DOE-NEDepartment of Energy, Nuclear Energy
FEfinite element
FEMFinite Element Method
HITHierarchical Input Text
HPCHigh Performance Computing
I/OInput/Output
INLIdaho National Laboratory
MOOSEMultiphysics Object Oriented Simulation Environment
MPIMessage Passing Interface
SDDSoftware Design Description

Design Stakeholders and Concerns

Design Stakeholders

Stakeholders for MOOSE include several of the funding sources including DOE-NE and the INL. However, Since MOOSE is an open-source project, several universities, companies, and foreign governments have an interest in the development and maintenance of the MOOSE project.

Stakeholder Design Concerns

Concerns from many of the stakeholders are similar. These concerns include correctness, stability, and performance. The mitigation plan for each of these can be addressed. For correctness, Electromagnetics module development requires either regression or unit testing for all new code added to the repository. The project contains several comparisons against analytical solutions where possible and also other verification methods such as MMS. For stability, the Electromagnetics module (located within the MOOSE repository) maintains multiple branches to incorporate several layers of testing both internally and for dependent applications. Finally, performance tests are also performed as part of the the normal testing suite to monitor code change impacts to performance.

System Design

The Electromagnetics module inherits the wide range of pluggable systems from MOOSE. More information regarding MOOSE system design can be found in the framework System Design section. As a physics module/library, the electromagnetics module contains several physical models related to electrodynamics. These are summarized via documentation of the demonstration benchmarks and verification examples on the module home page. Documentation for each object, data structure, and process specific to the module are kept up-to-date alongside the MOOSE documentation. Expected failure modes and error conditions are accounted for via regression testing, and error conditions are noted in object documentation where applicable.

System Structure

The architecture of the Electromagnetics module consists of a core and several pluggable systems (both inherited from the MOOSE framework). The core of MOOSE consists of a number of key objects responsible for setting up and managing the user-defined objects of a finite element simulation. This core set of objects has limited extendability and exist for every simulation configuration that the module is capable of running.

AuxKernels

AuxVariables

BCs

InterfaceKernels

Kernels

Materials

Postprocessors

UserObjects

The MooseApp is the top-level object used to hold all of the other objects in a simulation. In a normal simulation a single MooseApp object is created and "run()". This object uses its Factory objects to build user defined objects which are stored in a series of Warehouse objects and executed. The Finite Element data is stored in the Systems and Assembly object while the domain information (the Mesh) is stored in the Mesh object. A series of threaded loops are used to run parallel calculations on the objects created and stored within the warehouses.

MOOSE's pluggable systems are documented on MOOSE website, and those for the Electromagnetics module are on this webpage, accessible through the high-level system links above. Each of these systems has a set of defined polymorphic interfaces and are designed to accomplish a specific task within the simulation. The design of these systems is fluid and is managed through agile methods and ticket request system either on GitHub (for MOOSE) or on the defined software repository for this application.

Data Design and Control

At a high level, the system is designed to process HIT input files to construct several objects that will constitute an FE simulation. Some of the objects in the simulation may in turn load other file-based resources to complete the simulation. Examples include meshes or data files. The system will then assemble systems of equations and solve them using the libraries of the Code Platform. The system can then output the solution in one or more supported output formats commonly used for visualization.

Human-Machine Interface Design

The Electromagnetics module is a command-line driven program. All interaction with the Electromagnetics module is ultimately done through the command line. This is typical for HPC applications that use the MPI interface for running on super computing clusters. Optional GUIs may be used to assist in creating input files and launching executables on the command line.

System Design Interface

All external system interaction is performed either through file I/O or through local API calls. Neither the Electromagnetics module, nor the MOOSE framework, nor the other MOOSE modules are designed to interact with any external system directly through remote procedure calls. Any code to code coupling performed using the framework are done directly through API calls either in a static binary or after loading shared libraries.

Security Structure

The Electromagnetics module does not require any elevated privileges to operate and does not run any stateful services, daemons or other network programs. Distributed runs rely on the MPI library.

Requirements Cross-Reference

  • electromagnetics: CurrentDensity / ADCurrentDensity
  • 4.1.1The system shall calculate the current density provided with electrostatic field calculations, using an AD material property for electrical conductivity.

    Specification(s): ad_exodiff

    Design: CurrentDensity / ADCurrentDensity

    Issue(s): #21095

    Collection(s): FUNCTIONAL

    Type(s): Exodiff

    38
  • 4.1.2The system shall calculate the current density provided with electrostatic field calculations, using a non-AD material property for electrical conductivity.

    Specification(s): non_ad_exodiff

    Design: CurrentDensity / ADCurrentDensity

    Issue(s): #21095

    Collection(s): FUNCTIONAL

    Type(s): Exodiff

    38
  • 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.

    Specification(s): em_ad_exodiff

    Design: CurrentDensity / ADCurrentDensity

    Issue(s): #21095

    Collection(s): FUNCTIONAL

    Type(s): Exodiff

    38
  • 4.1.4The 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.

    Specification(s): errors/two_vars, errors/ES_electric_field_var, errors/EM_potential_var

    Design: CurrentDensity / ADCurrentDensity

    Issue(s): #21095

    Collection(s): FUNCTIONALFAILURE_ANALYSIS

    Type(s): RunException

    353535
  • electromagnetics: EMRobinBC
  • 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.

    Specification(s): test

    Design: EMRobinBC

    Issue(s): #21098

    Collection(s): FUNCTIONAL

    Type(s): Exodiff

    14
  • 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.

    Specification(s): test

    Design: ADMatReactionEMRobinBCWaveguide Transmission Benchmark

    Issue(s): #21098

    Collection(s): FUNCTIONAL

    Type(s): Exodiff

    14

    Verification: Waveguide Transmission Benchmark

  • 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.

    Specification(s): absorbing_error

    Design: EMRobinBC

    Issue(s): #21100

    Collection(s): FUNCTIONALFAILURE_ANALYSIS

    Type(s): RunException

    11
  • electromagnetics: VectorEMRobinBC
  • 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.

    Specification(s): waves

    Design: VectorEMRobinBC

    Issue(s): #21077

    Collection(s): FUNCTIONAL

    Type(s): Exodiff

    38
  • 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.

    Specification(s): waves_jacobian_test

    Design: VectorEMRobinBC

    Issue(s): #21077

    Collection(s): FUNCTIONAL

    Type(s): PetscJacobianTester

    29
  • 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.

    Specification(s): waves_absorbing_error

    Design: VectorEMRobinBC

    Issue(s): #21100

    Collection(s): FUNCTIONALFAILURE_ANALYSIS

    Type(s): RunException

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

    Specification(s): dim_error

    Design: ReflectionCoefficient

    Issue(s): #13744

    Collection(s): FUNCTIONALFAILURE_ANALYSIS

    Type(s): RunException

    35

References

  1. ISO/IEC/IEEE 24765:2010(E). Systems and software engineering—Vocabulary. first edition, December 15 2010.[BibTeX]
  2. 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.[BibTeX]