BlackBear System Design Description

This template follows Idaho National Laboratory (INL) template TEM-140, "IT System Design Description."

Introduction

Many of the phenomena related to structural component degradation depend on the solutions of multiple physics models, which can be described by partial differential equations that provide spatially and temporally varying values of solution variables. These models for individual physics often depend on each other. BlackBear relies on the MOOSE framework to solve these physics models, accounting for the couplings that may occur between them. This document describes the system design of BlackBear.

System Purpose

The Software Design Description provided here is description of each object in the system. The pluggable architecture of the underlying framework of BlackBear makes Multiphysics Object Oriented Simulation Environment (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 BlackBear. More information about the design documentation for MOOSE-based applications like BlackBear can be found in Documenting MOOSE.

System Scope

BlackBear models the effects of environmental exposure on structures. The environmental conditions that can induce aging include evolving mechanical loading and exposure to temperature and moisture. The materials modeled by BlackBear include those typically used in the construction of civil structures, such as concrete and steel. Under normal service, these structures can experience a variety of degradation mechanisms. For example, steel and other metals can degrade due to corrosion, embrittlement, and stress corrosion cracking. Concrete can experience degradation due to expansive reactions, chemical attacks, leaching, and mechanical mechanisms induced by conditions such as freeze/thaw cycles and fatigue.

In addition to modeling the degradation mechanisms, BlackBear also models the response of these structures to a variety of loading conditions that these structures are expected to safely withstand. These include a variety of normal thermal and mechanical service loading conditions, as well as wind and earthquake loading conditions. BlackBear includes models to represent the behavior of structural materials under those conditions, which can induce creep, plasticity, damage, fracture, and failure of these materials.

Dependencies and Limitations

BlackBear inherits the software dependencies of the MOOSE framework, with no additional dependencies.

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
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 Department of Energy, Nuclear Energy (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, BlackBear 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, BlackBear 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

BlackBear relies on MOOSE to solve the coupled physics models underlying structural component degradation, accounting for the couplings that may occur between them. The design of MOOSE is based on the concept of modular code objects that define all of the aspects of the physics model. BlackBear follows this design, providing code objects that define specific aspects of the solutions for its physics that derive from the base classes defined by the MOOSE framework and the modules that it depends on.

BlackBear provides specialized Kernel classes that compute the contributions from the terms in the partial differential equations for thermal and moisture transport in concrete. It also provides specialized Material classes that define the constitutive behavior of materials of interest for structural components. In addition, it provides miscellaneous BC, Action, and Postprocessor classes to facilitate various aspects of these simulations. Much of the functionality of BlackBear is provided by the MOOSE modules that it builds on.

System Structure

BlackBear relies on the MOOSE framework to provide the core functionality of solving multiphysics problems using the finite element method. It also relies on the MOOSE modules such as Solid Mechanics and Heat Transfer for much of its core functionality. The structure of BlackBear is based on defining C++ classes that derive from classes in the MOOSE framework or modules that provide functionality that is specifically tailored to the structural degradation problem. By using the interfaces defined in MOOSE base classes for these classes, BlackBear is able to rely on MOOSE to execute these models at the appropriate times during the simulation and use their results in the desired ways.

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

The BlackBear application is a command-line driven program. All interaction with BlackBear is ultimately done through the command line. This is typical for High Performance Computing (HPC) applications that use the Message 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 BlackBear, nor the MOOSE framework, nor the 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 BlackBear application 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

  • blackbear: Mazars Damage
  • 2.12.1BlackBear shall provide the Mazars model for scalar damage of concrete, predicting the correct response of a unit cube loaded
    1. in tension
    2. and in compression.

    Specification(s): mazars_damage/mazars_tension, mazars_damage/mazars_compression

    Design: Mazars Damage

    Issue(s): #24

    Collection(s): FUNCTIONAL

    Type(s): Exodiff

  • 2.12.2The MazarsDamage model shall generate an error if used with a material that is not guaranteed isotropic

    Specification(s): mazars_damage_isotropic_error

    Design: Mazars Damage

    Issue(s): #24

    Collection(s): FUNCTIONALFAILURE_ANALYSIS

    Type(s): RunException

  • 2.13.1BlackBear shall provide the Mazars scalar damage model for concrete, correctly predicting the response of a multi-element concrete bar loaded in tension

    Specification(s): tensile_bar

    Design: Mazars Damage

    Issue(s): #24

    Collection(s): FUNCTIONAL

    Type(s): Exodiff

  • blackbear: NEML Stress
  • 2.15.1Blackbear shall be capable of running a TM model with inelastic material exhibiting linear strain hardening.

    Specification(s): neml_LSH

    Design: NEML Stress

    Issue(s): #59

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • 2.15.2Blackbear shall be capable of using the NEML library to simulate an inelastic material exhibiting linear strain hardening.

    Specification(s): TM_LSH

    Design: NEML Stress

    Issue(s): #59

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • 2.15.3Blackbear shall be capable of running a TM model with inelastic material exhibiting power law creep behavior.

    Specification(s): test5a_lim

    Design: NEML Stress

    Issue(s): #59

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • 2.15.4Blackbear shall be capable of using the NEML library to simulate an inelastic material exhibiting power law creep behavior.

    Specification(s): test5a_lim_neml

    Design: NEML Stress

    Issue(s): #59

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • 2.16.1BlackBear shall be capable of using the NEML library to compute the response of an inelastic material

    Specification(s): neml_inelastic

    Design: NEML Stress

    Issue(s): #59

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • 2.16.2BlackBear shall be capable of using a timestep limit computed by the NEML coupling material

    Specification(s): neml_inelastic_dt

    Design: NEML Stress

    Issue(s): #169

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • 2.17.1BlackBear shall output the damage value for NEML models.

    Specification(s): neml_damage_output

    Design: NEML Stress

    Issue(s): #305

    Collection(s): FUNCTIONAL

    Type(s): Exodiff

  • 2.19.1BlackBear shall be capable of interfacing with the NEML library to compute stress

    Specification(s): neml_linear_elastic

    Design: NEML Stress

    Issue(s): #59

    Collection(s): SYSTEM

    Type(s): CSVDiff

  • 2.19.2BlackBear shall be capable of using the NEML library to compute the response of a linearly elastic material parsed from xml. Parameters defined in the xml can be overwritten by variables in the input file.

    Specification(s): neml_linear_elastic_variableOverwrite

    Design: NEML Stress

    Issue(s): #59

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • 2.19.3BlackBear shall be capable of using the NEML library to compute the response of a linearly elastic material defined in a material class

    Specification(s): neml_linear_elastic_simpleMaterial

    Design: NEML Stress

    Issue(s): #78

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • 2.19.4BlackBear shall be capable of interfacing with the NEML library to compute thermal expansion

    Specification(s): neml_linear_elastic_thermal

    Design: NEML StressNEML Thermal Expansion Eigenstrain

    Issue(s): #59

    Collection(s): SYSTEM

    Type(s): CSVDiff

  • 2.20.1BlackBear shall provide the ability to use the NEML library to model material response, and allow for parameters defined in the xml file to be overridden in the BlackBear input file

    Specification(s): neml_simple_stochastic

    Design: NEML Stress

    Issue(s): #78

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • blackbear: CauchyStressFromNEML
  • 2.18.1Jacobian is exact with relative tolerance of 1e-7 for small strain kinematics using the total Lagrangian formulation

    Specification(s): small_total

    Design: CauchyStressFromNEML

    Issue(s): #312

    Collection(s): FUNCTIONAL

    Type(s): PetscJacobianTester

  • 2.18.2Jacobian is exact with relative tolerance of 1e-7 for small strain kinematics using the updated Lagrangian formulation

    Specification(s): small_updated

    Design: CauchyStressFromNEML

    Issue(s): #312

    Collection(s): FUNCTIONAL

    Type(s): PetscJacobianTester

  • 2.18.3Jacobian is exact with relative tolerance of 1e-7 for large strain kinematics using the total Lagrangian formulation

    Specification(s): large_total

    Design: CauchyStressFromNEML

    Issue(s): #312

    Collection(s): FUNCTIONAL

    Type(s): PetscJacobianTester

  • 2.18.4Jacobian is exact with relative tolerance of 1e-7 for large strain kinematics using the updated Lagrangian formulation

    Specification(s): large_updated

    Design: CauchyStressFromNEML

    Issue(s): #312

    Collection(s): FUNCTIONAL

    Type(s): PetscJacobianTester

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]

ActionComponents

Adaptivity

Adaptivity/Indicators

Adaptivity/Markers

Application

AuxKernels

AuxScalarKernels

AuxVariables

BCs

BCs/CavityPressure

BCs/CoupledPressure

BCs/InclinedNoDisplacementBC

BCs/NonReflectingBC

BCs/Periodic

BCs/Pressure

BCs/SeismicDisplacement

BCs/SeismicForce

Bounds

ChainControls

Constraints

Constraints/EqualValueEmbeddedConstraint

Contact

Controls

Convergence

Correctors

Covariance

DGKernels

Dampers

Debug

Debug/MaterialDerivativeTest

DeprecatedBlock

DiracKernels

DiracKernels/SeismicSource

Distributions

DomainIntegral

Executioner

Executioner/Adaptivity

Executioner/Predictor

Executioner/Quadrature

Executioner/TimeIntegrator

Executioner/TimeIntegrators

Executioner/TimeStepper

Executioner/TimeSteppers

Executors

ExplicitDynamicsContact

FVBCs

FVICs

FVInterfaceKernels

FVKernels

FluidProperties

FluidPropertiesInterrogator

Functions

FunctorMaterials

GlobalParams

GrayDiffuseRadiation

HDGKernels

ICs

InterfaceKernels

Kernels

Kernels/DynamicSolidMechanics

Kernels/DynamicTensorMechanics

Kernels/PoroMechanics

Kernels/SolidMechanics

Kernels/TensorMechanics

Likelihood

LinearFVBCs

LinearFVKernels

Mastodon

Mastodon/Model

Mastodon/Outputs

Materials

Materials/I_Soil

Mesh

Mesh/BatchMeshGeneratorAction

Mesh/Partitioner

MeshDivisions

MeshModifiers

Modules

Modules/CompressibleNavierStokes

Modules/FluidProperties

Modules/HeatTransfer

Modules/HeatTransfer/ThermalContact

Modules/HeatTransfer/ThermalContact/BC

Modules/IncompressibleNavierStokes

Modules/NavierStokesFV

Modules/TensorMechanics

Modules/TensorMechanics/CohesiveZoneMaster

Modules/TensorMechanics/DynamicMaster

Modules/TensorMechanics/GeneralizedPlaneStrain

Modules/TensorMechanics/GlobalStrain

Modules/TensorMechanics/LineElementMaster

Modules/TensorMechanics/Master

Modules/TensorMechanics/MaterialVectorBodyForce

MortarGapHeatTransfer

MultiApps

NEML2

NodalKernels

NodalNormals

Outputs

ParameterStudy

Physics

Physics/Diffusion

Physics/Diffusion/ContinuousGalerkin

Physics/Diffusion/FiniteVolume

Physics/HeatConduction

Physics/HeatConduction/FiniteElement

Physics/HeatConduction/FiniteVolume

Physics/NavierStokes

Physics/NavierStokes/Flow

Physics/NavierStokes/FlowSegregated

Physics/NavierStokes/FluidHeatTransfer

Physics/NavierStokes/FluidHeatTransferSegregated

Physics/NavierStokes/ScalarTransport

Physics/NavierStokes/ScalarTransportSegregated

Physics/NavierStokes/SolidHeatTransfer

Physics/NavierStokes/Turbulence

Physics/NavierStokes/TwoPhaseMixture

Physics/NavierStokes/TwoPhaseMixtureSegregated

Physics/SolidMechanics

Physics/SolidMechanics/CohesiveZone

Physics/SolidMechanics/Dynamic

Physics/SolidMechanics/GeneralizedPlaneStrain

Physics/SolidMechanics/GlobalStrain

Physics/SolidMechanics/LineElement

Physics/SolidMechanics/LineElement/QuasiStatic

Physics/SolidMechanics/MaterialVectorBodyForce

Physics/SolidMechanics/QuasiStatic

Positions

Postprocessors

Preconditioning

Problem

ProjectedStatefulMaterialStorage

RayBCs

RayKernels

Reporters

Samplers

ScalarKernels

StochasticTools

Surrogates

ThermalContact

Times

Trainers

Transfers

UserObjects

VariableMappings

Variables

VectorPostprocessors

XFEM