BlackBear System Requirements Specification

System Purpose

The purpose of BlackBear is to simulate the progression of degradation in structural components (e.g., buildings, bridges, dams) due to exposure to the environmental conditions they experience over their lifetime. In addition, BlackBear predicts the response of those structures in the presence of that long-term degradation to loading conditions of interest to assess the effects of degradation on their integrity.

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.

System Context

The BlackBear application is command-line driven. Like MOOSE, this is typical for a high-performance software that is designed to run across several nodes of a cluster system. As such, all usage of the software is through any standard terminal program generally available on all supported operating systems. Similarly, for the purpose of interacting through the software, there is only a single user, "the user", which interacts with the software through the command-line. BlackBear does not maintain any back-end database or interact with any system daemons. It is an executable, which may be launched from the command line and writes out various result files as it runs.

Figure 1: Usage of BlackBear and other MOOSE-based applications.

System Functions

Since BlackBear is a command-line driven application, all functionality provided in the software is operated through the use of standard UNIX command line flags and the extendable MOOSE input file. BlackBear is completely extendable so individual design pages should be consulted for specific behaviors of each user-defined object.

User Characteristics

BlackBear has three main classes of users:

• BlackBear Developers: These are the core developers of BlackBear. They are responsible for designing, implementing, and maintaining the software, while following and enforcing its software development standards.

• Developers: These are scientists or engineers that modify or add capabilities to BlackBear for their own purposes, which may include research or extending its capabilities. They will typically have a background in structural or mechanical engineering, and in modeling and simulation techniques, but may have more limited background in code development using the C++ language. In many cases, these developers will be encouraged to contribute code back to BlackBear.

• Analysts: These are users that run BlackBear to run simulations, but do not develop code. The primary interface of these users with BlackBear is the input files that define their simulations. These users may interact with developers of the system requesting new features and reporting bugs found.

Assumptions and Dependencies

The BlackBear application is developed using MOOSE and is based on various modules, as such the SRS for BlackBear is dependent upon the files listed at the beginning of this document. Any further assumptions or dependencies are outlined in the remainder of this section.

BlackBear has no constraints on hardware and software beyond those of the MOOSE framework and modules listed in their respective SRS documents, which are accessible through the links at the beginning of this document.

BlackBear provides access to a number of code objects that perform computations such as material behavior and boundary conditions. These objects each make their own physics-based assumptions, such as the units of the inputs and outputs. Those assumptions are described in the documentation for those individual objects.

Definitions

• 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

Functional Requirements

• blackbear: Averageextensionratio
• 2.1.1AverageExtensionRatio computes the average extension ratio between two sets of points specified in two arrays: first_point and last_point. It should result in error when sizes of first_point and last_point do not match and size of first_point is zero
  1. The system shall provide a postprocessor that computes the average extension ratio between two sets of points.
  2. AverageExtensionRatio shall generate an error if the sizes of the specified sets of points do not match.
  3. AverageExtensionRatio shall generate an error if the size of either of the sets of points is zero.

• blackbear: Actions
• 2.2.1The system shall set up a set of equal value constraintstying the nodes in multiple blocks to a primary block formultiple variables.
  1. without using an action
  2. using the EqualValueEmbeddedConstraint action to automatically set up multiple constraints with the same results as without using the action.
  3. using multiple instances of the EqualValueEmbeddedConstraint action to set up multiple constraints with the same results as without using the action.
• 2.2.2The EqualValueEmbeddedConstraintAction shall generate an error if sizes of 'primary_variable' and 'variable' are different

• blackbear: Concrete Asr Swelling
• 2.3.1Blackbear shall solve coupled systems of equations for heat and moisure transfer and mechanical deformation in concrete, used as inputs for modeling expansion induced by alkali-silica reaction, as demonstrated by simulating a concrete cylinder confined by a steel jacket
  1. with anisotropic expansion strains,
  2. with anisotropic expansion strains and temperature in Kelvin unit,
  3. with isotropic expansion strains,
  4. with uniaxial tenile loading,
  5. and with a mesh that captures a larger axial region of the cylinder.
• 2.3.2Blackbear shall produce an error message when number of iterations exceeds max_its during the volumeteric strain residual calculation

• blackbear: Concrete Asr Validation
• 2.4.1Blackbear shall model the expansion induced by alkali-silica reaction as demonstrated with
  1. a comparison of the ASR volumetric strain to an analytic function,
  2. a maximum volumetric expansion of 0.76e-3, characteristic time of 66.84, and latency time of -126.1,
  3. and a maximum volumetric expansion of 0.38e-3, characteristic time of 17.24, and latency time of -2.55.

• blackbear: Concrete Anisotropic Eigenstrain
• 2.5.1BlackBear shall represent anisotropic volumetric expansion in concrete due to alkali-silica reaction and related phenomena as demonstrated by computing the expansion of a unit cube with a prescribed expansion function in the three coordinate directions
  1. under free expansion conditions,
  2. with a 5 MPa compressive pressure in the x direction,
  3. with a 50 MPa compressive pressure in the x direction,
  4. with 5 MPa compressive pressure in the x and y directions,
  5. with 10 MPa compressive pressure in the x and y directions,
  6. with 5 MPa compressive pressure in the x, y, and z directions,
  7. and with 10 MPa compressive pressure in the x, y, and z directions.
• 2.5.2Blackbear shall produce an error message when parameter(s) required for the anisotropic expansion_type are not set by user:
  1. Anisotropic expansion_type shall generate error if compressive_strength is not set by user.
  2. Anisotropic expansion_type shall generate error if expansion_stress_limit is not set by user.
  3. Anisotropic expansion_type shall generate error if tensile_strength is not set by user.

• blackbear: Concrete Drying Shrinkage
• 2.6.1BlackBear shall compute drying shrinkage of concrete
  1. with an exponent of 1,
  2. with an exponent of 2,
  3. and with an irreversibility threshold of 0.2.

• blackbear: Concrete Expansion Microcracking
• 2.7.1BlackBear shall represent damage in concrete due to alkali-silica reaction and related phenomena with anisotropy accounted for via the damage model as demonstrated by computing the expansion of a unit cube with a prescribed expansion function in the three coordinate directions
  1. under free expansion conditions,
  2. under free shrinkage conditions,
  3. under free expansion conditions excluding confinement effect,
  4. under free expansion conditions without the assumption of isotropic expansion,
  5. with a 5 MPa compressive pressure in the x direction,
  6. with a 10 MPa compressive pressure in the x direction,
  7. with a 5 MPa compressive pressure in the x and y directions,
  8. with a 10 MPa compressive pressure in the x and y directions,
  9. with a 5 MPa compressive pressure in the x, y, and z directions,
  10. and with a 10 MPa compressive pressure in the x, y, and z directions.
• 2.7.2The ConcreteExpansionMicrocrackingDamage model shall generate an error if used with a material that is not guaranteed isotropic
• 2.7.3Blackbear shall produce an error message when
  1. considering confinement effect without specifying expansion_stress_limit.
  2. considering confinement effect with negative expansion_stress_limit.

• blackbear: Concrete Logcreep
• 2.8.1BlackBear shall compute logarithmic viscoelastic behavior of concrete
  1. under standard conditions,
  2. under drying conditions,
  3. under low relative humidity,
  4. without recoverable creep,
  5. and at high temperature.

• blackbear: Concrete Moisture Heat Transfer
• 2.9.1Blackbear shall model heat transfer and moisture transport in concrete, producing results from a 1D axisymmetric simulation that are comparable to those obtained in the MAQBETH experiment under the following scenarios:
  1. Using mass lumping and using a moisture model that does not provide moisture capacity
  2. Using mass lumping and using a moisture model that provides moisture capacity
  3. Without using mass lumping and using a moisture model that does not provide moisture capacity
  4. Without using mass lumping and using a moisture model that provides moisture capacity
• 2.9.2Blackbear shall compute the heat capacity and thermal conductivity for concrete for the following models and options:
  1. Constant thermal model.
  2. ASCE-1992 siliceous thermal model.
  3. ASCE-1992 carbonate thermal model.
  4. Kodur-2004 siliceous thermal model.
  5. Kodur-2004 carbonate thermal model.
  6. Eurocode-2004 thermal model.
• 2.9.3Blackbear shall compute the moisture capacity (where applicable) and moisture diffusivity for concrete for the following models and options:
  1. Bazant moisture model.
  2. Mensi moisture model.
  3. Xi moisture model for cement type = 1 and aggregate_pore_type = dense
  4. Xi moisture model for cement type = 2 and aggregate_pore_type = dense
  5. Xi moisture model for cement type = 3 and aggregate_pore_type = dense
  6. Xi moisture model for cement type = 4 and aggregate_pore_type = dense
  7. Xi moisture model for cement type = 1 and aggregate_pore_type = porous
  8. Xi moisture model for cement type = 2 and aggregate_pore_type = porous
  9. Xi moisture model for cement type = 3 and aggregate_pore_type = porous
  10. Xi moisture model for cement type = 4 and aggregate_pore_type = porous
• 2.9.4Blackbear shall produce an error message when parameter(s) required for the following models are not set by user:
  1. Constant thermal model shall generate error if ref_density is not set by user.
  2. Constant thermal model shall generate error if ref_specific_heat is not set by user.
  3. Constant thermal model shall generate error if ref_thermal_conductivity is not set by user.
  4. ASCE-1992 thermal model shall generate error if aggregate_type is not set by user.
  5. Kodur-2004 thermal model shall generate error if aggregate_type is not set by user.
  6. Eurocode-2004 thermal model shall generate error if ref_density is not set by user.
  7. Eurocode-2004 thermal model shall generate error if ref_specific_heat is not set by user.
  8. Bazant moisture model shall generate error if D1 is not set by user.
  9. Bazant moisture model shall generate error if n is not set by user.
  10. Bazant moisture model shall generate error if critical_relative_humidity is not set by user.
  11. Bazant moisture model shall generate error if coupled_moisture_diffusivity_factor is not set by user.
  12. Mensi moisture model shall generate error if A is not set by user.
  13. Mensi moisture model shall generate error if B is not set by user.
  14. Mensi moisture model shall generate error if cement_mass is not set by user.
  15. Mensi moisture model shall generate error if water_to_cement_ratio is not set by user.
  16. Xi moisture model shall generate error if cement_type is not set by user.
  17. Xi moisture model shall generate error if aggregate_pore_type is not set by user.
  18. Xi moisture model shall generate error if aggregate_vol_fraction is not set by user.
  19. Xi moisture model shall generate error if concrete_cure_time is not set by user.
  20. Xi moisture model shall generate error if cement_mass is not set by user.
  21. Xi moisture model shall generate error if aggregate_mass is not set by user.
  22. Xi moisture model shall generate error if water_to_cement_ratio is not set by user.
  23. Xi moisture model shall generate error if water_to_cement_ratio is set < 0.5.
  24. Kodur-2004 thermal model shall generate error if temperature is more than 635.
  25. Kodur-2004 thermal model shall generate error if temperature is more than 1100.
  26. EUROCODE-2004 thermal model shall generate error if temperature is more than 1200.
  27. Bazant moisture model shall generate error if temperature is less than 25.

• blackbear: Damage Plasticity Model
• 2.10.1BlackBear shall provide a damaged plasticity model for concrete, which demonstrates the desired behavior
  1. in uniaxial tensile loading.
  2. in uniaxial compressive loading.
  3. when factor_controlling_dilatancy is changed.
  4. in shear loading.
• 2.10.2Blackbear shall produce an error message when input required for the inelastic_models are not properly set by user:
  1. when inelastic_models is not given as damage_plasticity_model
  2. when inelastic_models has more than one model as input

• blackbear: Function Offset Bc
• 2.11.1Blackbear shall support Dirichlet type boundary conditions defined by a function
  1. for a planar boundary with positive offset location along nodal normal direction
  2. for a curved boundary with negative offset location along nodal normal direction

• 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.
• 2.12.2The MazarsDamage model shall generate an error if used with a material that is not guaranteed isotropic

• blackbear: Mazars Tensile Bar
• 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

• blackbear: Neml Ancillary
• 2.14.1NEMLStateAux outputs state to aux system
• 2.14.2NEMLMaterialPropertyReset in fact resets the state variable after reaching the critical temperature

• blackbear: Neml Benchmark
• 2.15.1Blackbear shall be capable of running a TM model with inelastic material exhibiting linear strain hardening.
• 2.15.2Blackbear shall be capable of using the NEML library to simulate an inelastic material exhibiting linear strain hardening.
• 2.15.3Blackbear shall be capable of running a TM model with inelastic material exhibiting power law creep behavior.
• 2.15.4Blackbear shall be capable of using the NEML library to simulate an inelastic material exhibiting power law creep behavior.

• blackbear: Neml Complex
• 2.16.1BlackBear shall be capable of using the NEML library to compute the response of an inelastic material
• 2.16.2BlackBear shall be capable of using a timestep limit computed by the NEML coupling material

• blackbear: Neml Damage
• 2.17.1BlackBear shall output the damage value for NEML models.

• blackbear: Neml Lagrangian Jacobian
• 2.18.1Jacobian is exact with relative tolerance of 1e-7 for small strain kinematics using the total Lagrangian formulation
• 2.18.2Jacobian is exact with relative tolerance of 1e-7 for small strain kinematics using the updated Lagrangian formulation
• 2.18.3Jacobian is exact with relative tolerance of 1e-7 for large strain kinematics using the total Lagrangian formulation
• 2.18.4Jacobian is exact with relative tolerance of 1e-7 for large strain kinematics using the updated Lagrangian formulation

• blackbear: Neml Simple
• 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.
• 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

• blackbear: Neml Stochasticsimple
• 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

• blackbear: Steel Creep Damage Oh
• 2.21.1Blackbear shall compute steel creep damage considering stress triaxiality as per Oh et al (2011)
  1. and apply it reduce the finite element stress of a simple problem to simulate creep failure.
  2. and apply it to reduce the finite element stress of a simple problem to simulate creep failure when using automatic differentiation.
  3. and apply it to reduce the finite element stress of a simple two-dimensional problem to simulatecreep failure when using automatic differentiation.
  4. and apply it to reduce the finite element stress of a simple two-dimensional problem to simulatecreep failure when using hand-coded Jacobians.
• 2.21.2Blackbear shall compute steel creep damage
  1. using a single creep strain name in the input.
  2. using a vector of creep strain names in the input to reproduce creep strain and damage from equivalent single power law.

Usability Requirements

Performance Requirements

System Interfaces

• blackbear: Neml Simple
• 2.19.1BlackBear shall be capable of interfacing with the NEML library to compute stress
• 2.19.4BlackBear shall be capable of interfacing with the NEML library to compute thermal expansion

System Operations

System Modes and States

MOOSE applications normally run in normal execution mode when an input file is supplied. However, there are a few other modes that can be triggered with various command line flags as indicated here:

Physical Characteristics

The BlackBear application is software only with no associated physical media. See System Requirements for a description of the minimum required hardware necessary for running the BlackBear application.

Environmental Conditions

Not Applicable

System Security

MOOSE-based applications such as BlackBear have no requirements or special needs related to system-security. The software is designed to run completely in user-space with no elevated privileges required nor recommended.

Information Management

BlackBear as well as the core MOOSE framework in its entirety will be made publicly available on an appropriate repository hosting site. Day-to-day backups and security services will be provided by the hosting service. More information about backups of the public repository on INL-hosted services can be found on the following page: GitHub Backups

Polices and Regulations

MOOSE-based applications must comply with all export control restrictions.

System Life Cycle Sustainment

MOOSE-based development follows various agile methods. The system is continuously built and deployed in a piecemeal fashion since objects within the system are more or less independent. Every new object requires a test, which in turn requires an associated requirement and design description. The BlackBear development team follows the NQA-1 standards.

Packaging, Handling, Shipping and Transportation

No special requirements are needed for packaging or shipping any media containing the MOOSE and BlackBear source code. However, some MOOSE-based applications that use the BlackBear code may be export-controlled, in which case all export control restrictions must be adhered to when packaging and shipping media.