Porous Flow System Design Description
This template follows INL template TEM-140, "IT System Design Description."
This document serves as an addendum to Framework System Design Description and captures information for SDD specific to the Porous Flow module.
!sqa dependencies suffix=sdd category=porous_flow
Introduction
The MOOSE Porous Flow 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 Porous Flow 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 Porous Flow module. More information about the design documentation for MOOSE-based applications and like the Porous Flow module can be found in Documenting MOOSE.
System Scope
By simply adding pieces of physics together in an input file, the Porous Flow module enables the user to model problems with any combination of fluid, heat, geomechanics and geochemistry.
Dependencies and Limitations
The Porous Flow module inherits the software dependencies and limitations of the MOOSE framework. It depends on the Fluid Properties module for all fluid property calculations, the Solid Mechanics module for the mechanical aspects of coupled flow and geomechanics models, and the Geochemistry module for coupled flow and geochemical reactions. The Porous Flow module currently has the following limitations in functionality:
As it depends on other physics modules for fluid properties, mechanics and geochemistry calculations, the Porous Flow module is limited to the capability of each of the physics modules listed above. For example, the only fluids that can be used are those that are made available in the Fluid Properties module.
Only a small selection of constitutive models for properties like relative permeability or porosity-permeability relationships are available to the user. If a user requires some other constitutive model, they must develop that functionality themselves.
The Porous Flow module was developed before the inclusion of Automatic Differentiation (AD) capability in MOOSE, and the physics kernels are not currently designed for AD materials, meaning that new functionality currently requires hand-coded Jacobian entries.
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, Porous Flow 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 Porous Flow 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 Porous Flow 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 Porous Flow module provides functionality to support simulations for fluid and heat flow in porous media. More detailed information on the theory of the module can be found on the module home page under the subsection "Module overview". Numerical implementation details for the module can be found on the same page, under the subsection "Implementation details". A requirement of each Porous Flow simulation is the PorousFlowDictator object, which holds information about the nonlinear solution variables within the module, as well as the number of fluid phases and fluid components in each simulation. This object ensures that all of the required derivative terms are included in the Jacobian to aid solver convergence.
Kernels for a wide range of transport physics, such as advection, diffusion, hydrodynamic dispersion, and heat conduction are provided, as well as Kernels that couple fluid and heat flow to geomechanics and geochemistry. These are listed in the governing equations alongside the terms of the governing equations that each kernel represents.
Various boundary conditions are provided to represent common cases, such as boundaries to represent large aquifers, or boundaries to model evapotranspiration at a surface. Similarly, a number of Dirac kernels objects are provided, from simple point sources to wellbores.
The Porous Flow module also provides several choices of constitutive equations for relative permeability, capillary pressure, porosity, and permeability etc. Saturation history dependent hysteresis in capillary pressure and relative permeability is also included.
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 Porous Flow 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.
AuxKernels
AuxVariables
BCs
DiracKernels
FVBCs
FVKernels
Functions
ICs
Kernels
Materials
Modules
Modules/PorousFlow
Modules/PorousFlow/BCs
PorousFlowBasicTHM
PorousFlowFullySaturated
PorousFlowUnsaturated
Postprocessors
UserObjects
Variables
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 Porous Flow 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 Porous Flow module is a command-line driven program. All interaction with the Porous Flow 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 Porous Flow 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 Porous Flow 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
!sqa cross-reference category=porous_flow