Level Set System Design Description

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

note

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

Framework System Design Description

Introduction

The MOOSE Level Set module is based on the MOOSE framework and thus 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 Level Set 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 Level Set module. More information about the design documentation for MOOSE-based applications and like the Level Set module can be found in Documenting MOOSE.

System Scope

The MOOSE Level Set module provides capabilities for solving a set of level set equations. The level set method is commonly used for front tracking problems. The advection of the level set equation is solved using the Galerkin finite element method, and is stabilized with streamline Upwind/Petrov-Galerkin method. To preserve the smooth profile of the regularized level set variable, a re-initialization step can be used through the MOOSE multi-app system. The solutions are verified against classical benchmark problems.

Dependencies and Limitations

The Level Set module inherits the software dependencies and limitations of the MOOSE framework. The Level Set module is in its relative infancy, so it may not have all the features desired by potential users. Notable features in development are the ability to trace in unmeshed cavities and from sideset-to-sideset ignoring the volumetric mesh intersections.

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

Acronym	Description
API	Application Programming Interface
DOE-NE	Department of Energy, Nuclear Energy
FE	finite element
HIT	Hierarchical Input Text
HPC	High Performance Computing
I/O	Input/Output
INL	Idaho National Laboratory
MOOSE	Multiphysics Object Oriented Simulation Environment
MPI	Message Passing Interface
SDD	Software 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, Level Set 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 Level Set 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 Level Set 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.

The level set module provides basic functionality to solve the level set equation. The detailed information on the theory can be found at Level Set Module Theory. Kernels for advection, stabilization and re-initialization are provided. Several functions to compute initial conditions for the level set variable are available. Adaptivity is achieved through a specialized MOOSE problem LevelSetProblem.

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 Level Set 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 or finite volume simulation. This core set of objects has limited extendability and exists for every simulation configuration that the module is capable of running.

Functions

Kernels

MultiApps

Postprocessors

Problem

Transfers

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 and/or Finite Volume data is stored in the Systems and Assembly objects 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 Level Set 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 Level Set module is a command-line driven program. All interaction with the Level Set 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 Level Set 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 Level Set 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

level_set: LevelSetOlssonBubble
8.1.1The level set module shall include the bubble function defined in Olsson and Kreiss (2005).
Specification(s): test
Design: LevelSetOlssonBubble
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): Exodiff
28
8.1.2The Olsson bubble function shall return correct derivatives for dual number points.
Specification(s): adjac
Design: LevelSetOlssonBubble
Issue(s): #20193
Collection(s): FUNCTIONAL
Type(s): PetscJacobianTester
23

level_set: LevelSetOlssonPlane
8.1.3The level set module shall include the plane function defined in Olsson and Kreiss (2005).
Specification(s): test
Design: LevelSetOlssonPlane
Issue(s): #15167
Collection(s): FUNCTIONAL
Type(s): Exodiff
28

level_set: LevelSetOlssonVortex
8.1.4The level set module shall include the vortex function defined in Olsson and Kreiss (2005) with an instantaneous reverse feature.
Specification(s): instantenous
Design: LevelSetOlssonVortex
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): Exodiff
28
8.1.5The level set module shall include the vortex function defined in Olsson and Kreiss (2005) with an cosine reverse feature.
Specification(s): cosine
Design: LevelSetOlssonVortex
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): Exodiff
28

level_set: LevelSetAdvection
8.2.1The LevelSetAdvection Kernel shall converage at the correct rate as tested by the method of manufactured solutions.
Specification(s): mms
Design: LevelSetAdvection
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): CSVDiff
28
8.2.2The level set module shall include the reinitialization scheme presented by Olsson and Kreiss (2005).
Specification(s): test
Design: LevelSetAdvection
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): Exodiff
28

level_set: Level Set Module
8.3.1The level set module shall be capable of solving the level set equation with original reinitialization.
Specification(s): full_original_reinitialization
Design: Level Set Module
Issue(s): #14849
Collection(s): FUNCTIONAL
Type(s): Exodiff
24
8.3.2The level set module shall be capable of solving the level set equation with modified reinitialization.
Specification(s): full_modified_reinitialization
Design: Level Set Module
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): Exodiff
24
8.4.1The level set module shall include the ability to transfer a non-linear variable between the parent and a sub-application.
Specification(s): copy
Design: Level Set Module
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): Exodiff
28
8.4.2The level set module shall include the ability to transfer refinement patterns, with multiple levels of refinement, to a sub-application.
Specification(s): test
Design: Level Set Module LevelSetMeshRefinementTransfer
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): Exodiff
28
8.4.3The level set module shall include the ability to transfer refinement patterns, with a single level of refinement, to a sub-application.
Specification(s): test
Design: Level Set Module LevelSetMeshRefinementTransfer
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): Exodiff
28
8.4.4The system shall return an error if parameters for an unsupported direction are passed to a transfer
Specification(s): parameter_error
Design: Level Set Module LevelSetMeshRefinementTransfer
Issue(s): #19451
Collection(s): FUNCTIONALFAILURE_ANALYSIS
Type(s): RunException
28
8.5.1The level set module shall use the method of manufactured solutions to test convergence of the level set equation and ensure that the level 0 solution is consistent.
Specification(s): level_00
Design: Level Set Module
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): CSVDiff
28
8.5.2The level set module shall use the method of manufactured solutions to test convergence of the level set equation and ensure that the level 1 solution is consistent.
Specification(s): level_01
Design: Level Set Module
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): CSVDiff
28
8.5.3The level set module shall use the method of manufactured solutions to test convergence of the level set equation and ensure that the level 2 solution is consistent.
Specification(s): level_02
Design: Level Set Module
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): CSVDiff
28
8.5.4The level set module shall use the method of manufactured solutions to test convergence of the level set equation and ensure that the level 3 solution is consistent.
Specification(s): level_03
Design: Level Set Module
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): CSVDiff
28
8.5.5The level set module shall use the method of manufactured solutions to test convergence of the level set equation and ensure that the level 4 solution is consistent.
Specification(s): level_04
Design: Level Set Module
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): CSVDiff
28
8.5.6The level set module shall use the method of manufactured solutions to test convergence of the level set equation with SUPG and ensure that the level 0 solution is consistent.
Specification(s): level_00
Design: Level Set Module
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): CSVDiff
28
8.5.7The level set module shall use the method of manufactured solutions to test convergence of the level set equation with SUPG and ensure that the level 1 solution is consistent.
Specification(s): level_01
Design: Level Set Module
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): CSVDiff
28
8.5.8The level set module shall use the method of manufactured solutions to test convergence of the level set equation with SUPG and ensure that the level 2 solution is consistent.
Specification(s): level_02
Design: Level Set Module
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): CSVDiff
28
8.5.9The level set module shall use the method of manufactured solutions to test convergence of the level set equation with SUPG and ensure that the level 3 solution is consistent.
Specification(s): level_03
Design: Level Set Module
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): CSVDiff
28
8.5.10The level set module shall use the method of manufactured solutions to test convergence of the level set equation with SUPG and ensure that the level 4 solution is consistent.
Specification(s): level_04
Design: Level Set Module
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): CSVDiff
28

level_set: LevelSetMeshRefinementTransfer
8.4.2The level set module shall include the ability to transfer refinement patterns, with multiple levels of refinement, to a sub-application.
Specification(s): test
Design: Level Set Module LevelSetMeshRefinementTransfer
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): Exodiff
28
8.4.3The level set module shall include the ability to transfer refinement patterns, with a single level of refinement, to a sub-application.
Specification(s): test
Design: Level Set Module LevelSetMeshRefinementTransfer
Issue(s): #8465
Collection(s): FUNCTIONAL
Type(s): Exodiff
28
8.4.4The system shall return an error if parameters for an unsupported direction are passed to a transfer
Specification(s): parameter_error
Design: Level Set Module LevelSetMeshRefinementTransfer
Issue(s): #19451
Collection(s): FUNCTIONALFAILURE_ANALYSIS
Type(s): RunException
28

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"
}

Elin Olsson and Gunilla Kreiss. A conservative level set method for two phase flow. Journal of computational physics, 210(1):225–246, 2005. URL: http://dx.doi.org/10.1016/j.jcp.2005.04.007.

@article{olsson2005conservative,
    author = "Olsson, Elin and Kreiss, Gunilla",
    title = "A conservative level set method for two phase flow",
    journal = "Journal of computational physics",
    volume = "210",
    number = "1",
    pages = "225--246",
    year = "2005",
    publisher = "Elsevier",
    url = "http://dx.doi.org/10.1016/j.jcp.2005.04.007"
}


[./test]
  type = Exodiff
  input = olsson_bubble.i
  exodiff = olsson_bubble_out.e
  issues = '#8465'
  requirement = "The level set module shall include the bubble function defined in [!cite](olsson2005conservative)."
[../]


[./adjac]
  type = PetscJacobianTester
  input = olsson_bubble_adjac.i
  ratio_tol = 1e-7
  issues = '#20193'
  requirement = "The Olsson bubble function shall return correct derivatives for dual number points."
[../]


[./instantenous]
  type = Exodiff
  input = olsson_vortex.i
  exodiff = olsson_vortex_out.e
  requirement = "The level set module shall include the vortex function defined in [!cite](olsson2005conservative) with an instantaneous reverse feature."
[../]


[./cosine]
  type = Exodiff
  input = olsson_vortex.i
  cli_args = "Functions/velocity_func/reverse_type=cosine Outputs/file_base=olsson_vortex_cosine_out"
  exodiff = olsson_vortex_cosine_out.e
  requirement = "The level set module shall include the vortex function defined in [!cite](olsson2005conservative) with an cosine reverse feature."
[../]


[./mms]
  type = CSVDiff
  input = advection_mms.i
  csvdiff = advection_mms_out.csv
  # This problem uses SuperLU.
  capabilities = 'superlu'
  requirement = "The LevelSetAdvection Kernel shall converage at the correct rate as tested by the method of manufactured solutions."
[../]


[./test]
  type = Exodiff
  input = olsson_1d.i
  exodiff = olsson_1d_out.e
  requirement = "The level set module shall include the reinitialization scheme presented by [!cite](olsson2005conservative)."
  valgrind = HEAVY
[../]


[./full_original_reinitialization]
  # Runs two steps of a full original reinitialization problem just to make sure it continues to work
  type = Exodiff
  input = parent.i
  exodiff = parent_original.e
  cli_args = 'Executioner/num_steps=2 Outputs/file_base=parent_original'
  capabilities = 'method!=dbg' # complete reinitilization solve, debug is slow and not needed
  valgrind = HEAVY
  requirement = "The level set module shall be capable of solving the level set equation with original reinitialization."
  issues = '#14849'
[../]


[./full_modified_reinitialization]
  # Runs two steps of a full modified reinitialization problem just to make sure it continues to work
  type = Exodiff
  input = parent.i
  exodiff = parent_modified.e
  cli_args = 'Executioner/num_steps=2 Outputs/file_base=parent_modified reinit:Kernels/reinit/use_modified_reinitilization_formulation=true'
  capabilities = 'method!=dbg' # complete reinitilization solve, debug is slow and not needed
  valgrind = HEAVY
  requirement = "The level set module shall be capable of solving the level set equation with modified reinitialization."
  issues = '#8465'
[../]


[./copy]
  type = Exodiff
  input = parent.i
  exodiff = parent_out_sub0.e
  requirement = "The level set module shall include the ability to transfer a non-linear variable between the parent and a sub-application."
[../]


[./test]
  type = Exodiff
  input = parent.i
  exodiff = 'parent_out.e parent_out.e-s002 parent_out.e-s003 parent_out.e-s004 parent_out_sub0.e parent_out_sub0.e-s002 parent_out_sub0.e-s003 parent_out_sub0.e-s004'
  requirement = "The level set module shall include the ability to transfer refinement patterns, with multiple levels of refinement, to a sub-application."
[../]


[test]
  type = Exodiff
  input = parent.i
  exodiff = 'parent_out.e parent_out_sub0_out.e'
  requirement = "The level set module shall include the ability to transfer refinement patterns, with a single level of refinement, to a sub-application."
  issues = '#8465'
[]


[parameter_error]
  type = RunException
  input = parent.i
  expect_err = 'from_multiapp or between_multiapp transfers are not supported'
  cli_args = 'Transfers/marker_to_sub/from_multi_app=sub'
  requirement = "The system shall return an error if parameters for an unsupported direction are passed to a transfer"
  issues = '#19451'
[]


[./level_00]
  type = CSVDiff
  input = level_set_mms.i
  csvdiff = level_set_mms_00.csv
  cli_args = 'Mesh/uniform_refine=0 Outputs/file_base=level_set_mms_00'
  requirement = "The level set module shall use the method of manufactured solutions to test convergence of the level set equation and ensure that the level 0 solution is consistent."
[../]


[./level_01]
  type = CSVDiff
  input = level_set_mms.i
  csvdiff = level_set_mms_01.csv
  cli_args = 'Mesh/uniform_refine=1 Outputs/file_base=level_set_mms_01'
  requirement = "The level set module shall use the method of manufactured solutions to test convergence of the level set equation and ensure that the level 1 solution is consistent."
[../]


[./level_02]
  type = CSVDiff
  input = level_set_mms.i
  csvdiff = level_set_mms_02.csv
  cli_args = 'Mesh/uniform_refine=2 Outputs/file_base=level_set_mms_02'
  requirement = "The level set module shall use the method of manufactured solutions to test convergence of the level set equation and ensure that the level 2 solution is consistent."
[../]


[./level_03]
  type = CSVDiff
  input = level_set_mms.i
  csvdiff = level_set_mms_03.csv
  cli_args = 'Mesh/uniform_refine=3 Outputs/file_base=level_set_mms_03'
  requirement = "The level set module shall use the method of manufactured solutions to test convergence of the level set equation and ensure that the level 3 solution is consistent."
[../]


[./level_04]
  type = CSVDiff
  input = level_set_mms.i
  csvdiff = level_set_mms_04.csv
  cli_args = 'Mesh/uniform_refine=4 Outputs/file_base=level_set_mms_04'
  requirement = "The level set module shall use the method of manufactured solutions to test convergence of the level set equation and ensure that the level 4 solution is consistent."
  valgrind = HEAVY
[../]


[./level_00]
  type = CSVDiff
  input = 1d_level_set_supg_mms.i
  csvdiff = 1d_level_set_supg_mms_00.csv
  cli_args = 'Mesh/uniform_refine=0 Outputs/file_base=1d_level_set_supg_mms_00'
  requirement = "The level set module shall use the method of manufactured solutions to test convergence of the level set equation with SUPG and ensure that the level 0 solution is consistent."
[../]


[./level_01]
  type = CSVDiff
  input = 1d_level_set_supg_mms.i
  csvdiff = 1d_level_set_supg_mms_01.csv
  cli_args = 'Mesh/uniform_refine=1 Outputs/file_base=1d_level_set_supg_mms_01'
  requirement = "The level set module shall use the method of manufactured solutions to test convergence of the level set equation with SUPG and ensure that the level 1 solution is consistent."
[../]


[./level_02]
  type = CSVDiff
  input = 1d_level_set_supg_mms.i
  csvdiff = 1d_level_set_supg_mms_02.csv
  cli_args = 'Mesh/uniform_refine=2 Outputs/file_base=1d_level_set_supg_mms_02'
  requirement = "The level set module shall use the method of manufactured solutions to test convergence of the level set equation with SUPG and ensure that the level 2 solution is consistent."
[../]


[./level_03]
  type = CSVDiff
  input = 1d_level_set_supg_mms.i
  csvdiff = 1d_level_set_supg_mms_03.csv
  cli_args = 'Mesh/uniform_refine=3 Outputs/file_base=1d_level_set_supg_mms_03'
  requirement = "The level set module shall use the method of manufactured solutions to test convergence of the level set equation with SUPG and ensure that the level 3 solution is consistent."
[../]


[./level_04]
  type = CSVDiff
  input = 1d_level_set_supg_mms.i
  csvdiff = 1d_level_set_supg_mms_04.csv
  cli_args = 'Mesh/uniform_refine=4 Outputs/file_base=1d_level_set_supg_mms_04'
  requirement = "The level set module shall use the method of manufactured solutions to test convergence of the level set equation with SUPG and ensure that the level 4 solution is consistent."
[../]


[./test]
  type = Exodiff
  input = parent.i
  exodiff = 'parent_out.e parent_out.e-s002 parent_out.e-s003 parent_out.e-s004 parent_out_sub0.e parent_out_sub0.e-s002 parent_out_sub0.e-s003 parent_out_sub0.e-s004'
  requirement = "The level set module shall include the ability to transfer refinement patterns, with multiple levels of refinement, to a sub-application."
[../]


[test]
  type = Exodiff
  input = parent.i
  exodiff = 'parent_out.e parent_out_sub0_out.e'
  requirement = "The level set module shall include the ability to transfer refinement patterns, with a single level of refinement, to a sub-application."
  issues = '#8465'
[]


[parameter_error]
  type = RunException
  input = parent.i
  expect_err = 'from_multiapp or between_multiapp transfers are not supported'
  cli_args = 'Transfers/marker_to_sub/from_multi_app=sub'
  requirement = "The system shall return an error if parameters for an unsupported direction are passed to a transfer"
  issues = '#19451'
[]

Introduction
Definitions and Acronyms
Design Stakeholders and Concerns
System Design
Functions
Kernels
MultiApps
Postprocessors
Problem
Transfers
UserObjects
Requirements Cross - Reference
References