Application Usage link

Physics and Syntax

Application Development link

Framework Development link

MOOSEDocs link

Infrastructure

Questions

Information and Tools

Framework System Design Description

Introduction

Frameworks are a software development construct aiming to simplify the creation of specific classes of applications through abstraction of low-level details. The main object of creating a framework is to provide an interface to application developers that saves time and provides advanced capabilities not attainable otherwise. The Multiphysics Object Oriented Simulation Environment (MOOSE), mission is just that: provide a framework for engineers and scientists to build state-of-the-art, computationally scalable finite element based simulation tools.

MOOSE was conceived with one major objective: to be as easy and straightforward to use by scientists and engineers as possible. MOOSE is meant to be approachable by non-computational scientists who have systems of PDEs they need to solve. Every single aspect of MOOSE was driven by this singular principle from the build system to the API to the software development cycle. At every turn, decisions were made to enable this class of users to be successful with the framework. The pursuit of this goal has led to many of the unique features of MOOSE:

  • A streamlined build system

  • An API aimed at extensible

  • Straightforward APIs providing sensible default information

  • Integrated, automatic, and rigorous testing

  • Rapid, continuous integration development cycle

  • Codified, rigorous path for contributing

  • Applications are modular and composable

Each of these characteristics is meant to build trust in the framework by those attempting to use it. For instance, the build system is the first thing potential framework users come into contact with when they download a new software framework. Onerous dependency issues, complicated, hard to follow instructions or build failure can all result in a user passing on the platform. Ultimately, the decision to utilize a framework comes down to whether or not you trust the code in the framework and those developing it to be able to support your desired use-case. No matter the technical capabilities of a framework, without trust users will look elsewhere. This is especially true of those not trained in software development or computational science.

Developing trust in a framework goes beyond utilizing "best practices" for the code developed, it is equally important that the framework itself is built upon tools that are trusted. For this reason, MOOSE relies on a well-established code base of libMesh and PETSc. The libMesh library provides foundational capability for the finite element method and provides interfaces to leading-edge numerical solution packages such as PETSc.

With these principles in mind, an open source, massively parallel, finite element, multiphysics framework has been conceived. MOOSE is an on-going project started in 2008 aimed toward a common platform for creation of new multiphysics tools. This document provides design details pertinent to application developers as well as framework developers.

Use Cases

The MOOSE Framework is targeted at two main groups of actors: Developers and Users. Developers are the main use case. These are typically students and professionals trained in science and engineering fields with some level of experience with coding but typically very little formal software development training. The other user group is Users. Those who intend to use an application built upon the framework without writing any computer code themselves. Instead they may modify or create input files for driving a simulation, run the application, and analyze the results. All interactions through MOOSE are primarily through the command-line interface and through a customizable block-based input file.

System Purpose

The Software Design Description provided here is description of each object in the system. The pluggable architecture of the framework 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 framework, modules and derivative applications. More information about the design documentation can be found in MooseDocs.

System Scope

The purpose of this software is to provide several libraries that can be used to build an application based upon the framework. Additionally, several utilities are provided for assisting developers and users in end-to-end Finite Element Method (FEM) analysis. A brief overview of the major components are listed here:

ComponentDescription
framework libraryThe base system from which all MOOSE-based applications are created
module librariesOptional "physics" libraries that may be used in an application to provide capability
build systemThe system responsible for creating applications for a series of libraries and applications
test harnessThe extendable testing system for finding, scheduling, running, and reporting regression tests
"peacock"The graphical user interface (GUI) for building input files, executing applications, and displaying results
MooseDocsThe extendable markdown system for MOOSE providing common documentation and requirements enforcement
"stork"The script and templates for generating a new MOOSE-based application ready for building and testing
examplesA set of complete applications demonstrating the use of MOOSE's pluggable systems
tutorialsStep by step guides to building up an application using MOOSE's pluggable systems
unitAn application for unit testing individual classes or methods of C++ code

Dependencies and Limitations

The MOOSE platform has several dependencies on other software packages and has scope that is constantly evolving based upon funding, resources, priorities, and lab direction. However, the software is open-source and many features and even bugs can be offloaded to developers with appropriate levels of knowledge and direction from the main design team. The primary list of software dependencies is listed below. This list is not meant to be exhaustive. Individual operating systems may require specific packages to be installed prior to using MOOSE, which can be found on the Getting Started pages.

Software DependencyDescription
libMeshFinite Element Library and I/O routines
PETScSolver Package
hypreMultigrid Preconditioner
MPIA distributed parallel processing library (MPICH)

Figure 1: A diagram of the MOOSE code platform.

References

  1. ISO/IEC/IEEE 24765:2010(E). Systems and software engineering—Vocabulary. first edition, December 15 2010.[BibTeX]
  2. D. F. Griffiths. The `No Boundary Condition' outflow boundary condition. International Journal of Numerical Methods in Fluids, 24(4):393–411, 1997. URL: http://tinyurl.com/y77au2k.[BibTeX]
  3. 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]

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
ADautomatic differentiation
APIApplication Programming Interface
CIVETContinuous Integration for Verification, Enhancement, and Testing
DOEDepartment of Energy
DOE-NEDepartment of Energy, Nuclear Energy
DOFdegree-of-freedom
FEFinite Element
FEMFinite Element Method
GUIgraphical user interface
HITHierarchical Input Text
HPCHigh Performance Computing
I/OInput/Output
INLIdaho National Laboratory
JFNKJacobian-Free Newton-Krylov
LGPLGNU Library General Public License
MMSMethod of Manufactured Solutions
MPIMethod Passing Interface
MOOSEMultiphysics Object Oriented Simulation Environment
NENuclear Energy
NQA-1Nuclear Quality Assurance Level 1
PETScPortable, Extensible Toolkit for Scientific Computation
POSIXPortable Operating System Interface
PDEpartial differential equation
PDEspartial differential equations
RTMRequirement Traceability Matrix
SDDSoftware Design Description
SRSSoftware Requirement Specification
STPSoftware Test Plan
VVRVerification and Validation Report

Design Stakeholders and Concerns

Design Stakeholders

Stakeholders for MOOSE include several of the funding sources including Department of Energy, Nuclear Energy (DOE-NE) and the Idaho National Laboratory (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, MOOSE 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, MOOSE 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 MOOSE framework itself is composed of a wide range of pluggable systems. Each system is generally composed of a single or small set of C++ objects intended to be specialized by a Developer to solve a specific problem. To accomplish this design goal, MOOSE uses several modern object-oriented design patterns. The primary overarching pattern is the "Factory Pattern". Users needing to extend MOOSE may inherit from one of MOOSE's systems to providing an implementation meeting his or her needs. The design of each of these systems is documented on the mooseframework.org wiki in the Tutorial section. Additionally, up-to-date documentation extracted from the source is maintained on the the mooseframework.org documentation site after every successful merge to MOOSE's stable branch. After these objects are created, the can be registered with the framework and used immediately in a MOOSE input file.

System Structure

The MOOSE framework architecture consists of a core and several pluggable systems. 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 framework is capable of running.

Available Subsystems

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 it's 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 the mooseframework.org wiki. Each of these systems has 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 on the Github.org website.

Data Design and Control

At a high level, the system is designed to process Hierarchical Input Text (HIT) input files to construct several objects that will constitute an Finite Element (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

MOOSE is a command-line driven program. All interaction with MOOSE and MOOSE-based codes is ultimately done through the command line. This is typical for High Performance Computing (HPC) applications that use the Method Passing Interface (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 Input/Output (I/O) or through local Application Programming Interface (API) calls. Neither the framework, nor the 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 framework 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

  • framework: BCs System
  • F1.4.19MOOSE shall support the creation of BoundaryCondition objects that support conditional activation.

    Specification: bcs/conditional_bc:test

    Design: BCs System

    87
  • F1.4.20MOOSE shall support the creation of BoundaryCondition objects that couple to nonlinear variables.

    Specification: bcs/coupled_dirichlet_bc:test

    Design: BCs System

    Issue(s): #656

    87
  • F1.4.24MOOSE shall support matching variable values on a boundary.

    Specification: bcs/matched_value_bc:test

    Design: BCs System

    Issue(s): #656

    87
  • F1.4.25MOOSE shall support the ability to create convective flux boundary conditions.

    Specification: bcs/misc_bcs:convective_flux_bc_test

    Design: BCs System

    87
  • F1.4.26MOOSE shall support a vacuum boundary condition for neutron diffusion on the boundary.

    Specification: bcs/misc_bcs:vacuumbc_test

    Design: BCs System

    87
  • F1.4.27MOOSE shall support Neumann type boundary conditions where the specified value is defined as the value of a vector, , in the direction of the boundary outward facing normal, (i.e., ).

    Specification: bcs/misc_bcs:vector_neumann_test

    Design: BCs System

    87
  • F1.4.28MOOSE shall support the 'no boundary condition' type boundary condition (Griffiths, 1997).

    Specification: bcs/misc_bcs:weak_gradient_bc_test

    Design: BCs System

    87
  • F1.4.55MOOSE shall properly compute second derivatives within BoundaryCondition objects.

    Specification: bcs/second_deriv:test_lap_bc

    Design: BCs System

    Issue(s): #6327

    87
  • F1.4.56MOOSE shall support creating sidesets from nodesets for hexahedron elements to use with Boundary Condition objects.

    Specification: bcs/sideset_from_nodeset:test_hex

    Design: Mesh SystemBCs System

    Issue(s): #687

    87
  • F1.4.57MOOSE shall support creating sidesets from nodesets for tetrahedron elements to use with Boundary Condition objects.

    Specification: bcs/sideset_from_nodeset:test_tet

    Design: Mesh SystemBCs System

    Issue(s): #687

    87
  • F1.4.60BoundaryCondition objects shall support retrieval of VectorPostprocessor data.

    Specification: bcs/vectorpostprocessor:test

    Design: BCs System

    Issue(s): #9285

    87
  • framework: AnnularMesh
  • F1.23.43MOOSEs annular mesh generator
    1. shall throw an error if the min radius is larger than the max radius.
    2. shall throw an error if the min angle is greater than or equal to the max angle.
    3. shall throw an error if the angle separation is larger than 360 degrees.
    4. shall throw an error if the number of elements in the angular direction is too small.
    5. shall throw an error if the number of elements in the angular direction is too small.
    6. shall throw an error if the quadrilateral and triangular subdomain ids are the same.
    7. shall create an annulus using quad elements.
    8. shall create an annulus sector using quad elements.
    9. shall create a circular disk using quad elements.
    10. shall create a circular disk sector using quad elements.

    Specification: mesh/mesh_generation:annular

    Design: AnnularMesh

    Issue(s): #8432

    60606060606087878787
  • framework: MeshExtruderGenerator
  • F1.24.36The system shall have the capability of extruding a lower dimensional mesh to create a higher dimensional mesh
    1. from 2D quads to 3D hexes,
    2. where newly created elements can be assigned a new subdomain IDs based on old IDs,
    3. where newly created elements can be assigned a new subdomain IDs based on a pattern,
    4. where the extrusion direction is not orthogonal to the original line or plane of elements, and
    5. where the extrusion occurs based on another generated mesh,
    6. while making sure to preserve existing side set names.

    Specification: meshgenerators/mesh_extruder_generator:extruder

    Design: MeshExtruderGenerator

    Issue(s): #11640#14037

    606060606060
  • framework: Checkpoint
  • F1.30.2The system shall support outputting of checkpoint files:
    1. at a specific interval while only maintaining a specified number of recent files and
    2. be capable of restarting a simulation from previously exported data at this interval.

    Specification: outputs/checkpoint:interval

    Design: Checkpoint

    Issue(s): #1927#2395

    6060
  • F1.30.3The system shall support outputting of checkpoint files, using a simplified input format:
    1. at every timestep while maintaining the most recent two files and
    2. be capable of restarting a simulation from the output data.

    Specification: outputs/checkpoint:default

    Design: Checkpoint

    Issue(s): #1927

    6060
  • F1.30.4The system shall support outputting of checkpoint files, using a complete input block:
    1. at every timestep while maintaining the most recent two files and
    2. be capable of restarting a simulation from the output data.

    Specification: outputs/checkpoint:block

    Design: Checkpoint

    Issue(s): #1927

    6060
  • framework: DOFMap
  • F1.30.59The system shall support the ability to output the degree-of-freedom information:
    1. to a json file,
    2. to the screen,
    3. with uniform refinement, and
    4. with transient adaptivity.

    Specification: outputs/dofmap:group

    Design: DOFMap

    Issue(s): #3847

    87608787
  • framework: VTK
  • F1.30.170The system shall optionally support output of files using the VTK format:
    1. in serial and
    2. in parallel.

    Specification: outputs/vtk:files

    Design: VTK

    Issue(s): #1927

    7676
  • F1.30.171The system shall optionally support output of solution data using the VTK format:
    1. in serial with a replicated mesh,
    2. in parallel with a replicated mesh, and
    3. in parallel with a distributed mesh.

    Specification: outputs/vtk:solution

    Design: VTK

    Issue(s): #1927

    5050
  • framework: Sampler
  • F1.41.1The system shall include a random number sampling system that operates in parallel
    1. with threads,
    2. MPI, and
    3. that operates with a row-based iteration scheme.

    Specification: samplers/base:parallel

    Design: Sampler

    Issue(s): #13906

    546060
  • F1.41.2The system shall include a random number sampling system that creates replicated and/or distribute sample data that is consistent:
    1. on a single processor,
    2. on a two processors,
    3. on a three processors,
    4. on a one processor with random numbers,
    5. on two processor with random numbers, and
    6. on thre processor with random numbers.

    Specification: samplers/base:global_vs_local

    Design: Sampler

    Issue(s): #13906

    606060606060
  • F1.41.3The system shall include a random number sampling system that errors
    1. if the number of rows is set after object construction,
    2. if the number of cols is set after object construction,
    3. if the number of random number generator seeds is set after object construction,
    4. if the number of rows is set to zero,
    5. if the number of columns is set to zero,
    6. if the number of random number generator seeds is set to zero,
    7. if the number of entries in the global sample matrix exceeds the maximum allowed,
    8. if the number of entries in the local sample matrix exceeds the maximum allowed, and
    9. if the number of entries in the local sample matrix row exceeds the maximum allowed.

    Specification: samplers/base:errors

    Design: Sampler

    Issue(s): #13906

    606060606060606060
  • F1.41.4The system shall include a random number sampling system
    1. that distributes samples in parallel and
    2. demonstrates efficient parallel scaling of memory use.

    Specification: samplers/distribute:scale

    Design: Sampler

    Issue(s): #13906

    5454
  • framework: ExplicitEuler
  • F1.44.19The system shall support the use of quasi-explicit Euler solver with
    1. 1D elements with first order shape functions and Dirichlet boundary conditions;
    2. 1D elements with second order shape functions and Dirichlet boundary conditions;
    3. 1D elements with second order shape functions and Neumann boundary conditions;
    4. 2D elements with first order shape functions and Dirichlet boundary conditions;
    5. 2D elements with second order shape functions and Dirichlet boundary conditions; and
    6. 2D elements with second order shape functions and Neumann boundary conditions.

    Specification: time_integrators/explicit-euler:group

    Design: ExplicitEuler

    Issue(s): #1953

    878787878787
  • framework: ExplicitMidpoint
  • F1.44.26The system shall support the use of an explicit midpoint time integration scheme for
    1. 1D elements with linear finite element shape functions and
    2. 2D elements with quadratic finite element shape functions.

    Specification: time_integrators/rk-2:group

    Design: ExplicitMidpoint

    Issue(s): #1953

    8787
  • F1.44.27The system shall compute the Jacobian during explicit midpoint time integration for
    1. 1D elements with linear finite element shape functions and
    2. 2D elements with quadratic finite element shape functions.

    Specification: time_integrators/rk-2:jacobian

    Design: ExplicitMidpoint

    Issue(s): #1953

    6060
  • framework: ExplicitTVDRK2
  • F1.44.29The system shall support the use of an total variation diminishing Runge-Kutta time integration schemefor
    1. 1D elements with linear finite element shape functions and
    2. 2D elements with quadratic finite element shape functions.

    Specification: time_integrators/tvdrk2:group

    Design: ExplicitTVDRK2

    Issue(s): #1953

    8787
  • F1.44.30The system shall compute the Jacobian during total variation diminishing Runge-Kutta time integration for
    1. 1D elements with linear finite element shape functions and
    2. 2D elements with quadratic finite element shape functions.

    Specification: time_integrators/tvdrk2:jacobian

    Design: ExplicitTVDRK2

    Issue(s): #1953

    6060
  • framework: DT2
  • F1.45.6The system shall include an adaptive, error-estimate based multi-step time step calculation scheme.

    Specification: time_steppers/dt2:testdt2

    Design: DT2

    Issue(s): #1953

  • framework: InterfaceQpValueUserObject
  • F1.47.6Testing the implementation of the InterfaceQpValueUserObject. This test also shows the use of InterfaceValueUserObjectAux AuxKernel. InterfaceValueUserObjectAux use interface values computed and stored at each qp from the InterfaceQpValueUserObject and output them into an auxvaraible.Values on the interface are then computed via SideAverageValue PP.By design at the end of the first step we should observe: an average material property of 7, an average material property absolute jump fo 6, a singed material property jump (master-slave) of 6 a singed material propertyjump (slave-master) of -6 a material property value on the master side of 10 a material property value on the master side of 4

    Specification: userobjects/interface_user_object:interface_UO_QP_test

    Design: InterfaceQpValueUserObjectInterfaceValueUserObjectAux

    Issue(s): #11647

    87
  • framework: InterfaceValueUserObjectAux
  • F1.47.6Testing the implementation of the InterfaceQpValueUserObject. This test also shows the use of InterfaceValueUserObjectAux AuxKernel. InterfaceValueUserObjectAux use interface values computed and stored at each qp from the InterfaceQpValueUserObject and output them into an auxvaraible.Values on the interface are then computed via SideAverageValue PP.By design at the end of the first step we should observe: an average material property of 7, an average material property absolute jump fo 6, a singed material property jump (master-slave) of 6 a singed material propertyjump (slave-master) of -6 a material property value on the master side of 10 a material property value on the master side of 4

    Specification: userobjects/interface_user_object:interface_UO_QP_test

    Design: InterfaceQpValueUserObjectInterfaceValueUserObjectAux

    Issue(s): #11647

    87