Shifted Boundary Method System Requirements Specification

System Purpose

!template! item key=system-purpose
Include text (in MooseDocs format) regarding the "system-purpose" template item here.
!template-end!

System Scope

!template! item key=system-scope
Include text (in MooseDocs format) regarding the "system-scope" template item here.
!template-end!

System Context

The Shifted Boundary Method module 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. The Shifted Boundary Method module 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 the Shifted Boundary Method module and other MOOSE-based applications.

System Functions

Since the Shifted Boundary Method module 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. The Shifted Boundary Method module is completely extendable so individual design pages should be consulted for specific behaviors of each user-defined object.

User Characteristics

Like MOOSE, there are three kinds of users working on the Shifted Boundary Method module:

• Shifted Boundary Method module Developers: These are the core developers of the Shifted Boundary Method module. They are responsible for following and enforcing the software development standards of the module, as well as designing, implementing, and maintaining the software.

• Developers: A scientist or engineer that uses the Shifted Boundary Method module alongside MOOSE to build their own application. This user will typically have a background in modeling or simulation techniques (and perhaps numerical analysis) but may only have a limited skillset when it comes to code development using the C++ language. This is the primary focus group of the module. In many cases, these developers will be encouraged to contribute module-appropriate code back to the Shifted Boundary Method module, or to MOOSE itself.

• Analysts: These are users that will run the code and perform analysis on the simulations they perform. These users may interact with developers of the system requesting new features and reporting bugs found and will typically make heavy use of the input file format.

Assumptions and Dependencies

The Shifted Boundary Method module is developed using MOOSE and can itself be based on various MOOSE modules, as such the SRS for the Shifted Boundary Method module 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.

!template! item key=assumptions-and-dependencies
Include text (in MooseDocs format) regarding the "assumptions-and-dependencies" template item here.
!template-end!

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

• shifted_boundary_method: Coverage
• 18.1.1The system shall
  1. report the closest distance vector and surface normal at element centroids when parsed-function and mesh-based surfaces are combined in a single query.
  2. build boundary element representations from an SBM surface mesh without a k-d tree when k-d tree construction is disabled.
  3. report when an SBM surface mesh is not watertight.
  4. return zero distance when the query point lies on the surface mesh.

• shifted_boundary_method: Distance Calc
• 18.2.1The system shall compute
  1. the distance field in 2D.
  2. the distance field in 3D.
  3. the distance field in 2D when signed level-set and mesh-based surfaces are combined.
  4. the distance field in 3D when signed level-set and mesh-based surfaces are combined.
  5. a signed distance field in 2D using a point-in-polyhedron in-out test to set the sign, including a gradient that points outward across the surface on both the interior and exterior sides.
  6. a signed distance field whose sign is supplied by a union checker through the point-in-surface check interface.
• 18.2.2The system shall throw an error
  1. if ElementCentroidToSurfaceDistanceAux is applied to a nodal variable.
  2. if ShortestDistanceToSurface receives a function whose type is not ParsedFunction, UnsignedDistanceToSurfaceMesh, or SignedDistanceToSurfaceMesh.
  3. if the embedding mesh dimension does not match the SBM surface mesh dimension plus one.
  4. if the SBM surface mesh contains element types other than EDGE2 or TRI3.
  5. if the SBM surface mesh is distributed, since SBMSurfaceMeshBuilder requires a replicated mesh for its In-Out test.
  6. if an UnsignedDistanceToSurfaceMesh function is paired with an SBMSurfaceMeshBuilder that was configured without a KDTree.
  7. if an UnsignedDistanceToSurfaceMesh function has neither a surface builder nor an interface manager.
  8. if an UnsignedDistanceToSurfaceMesh function has both a surface builder and an interface manager.
  9. if manager mode does not identify both subdomains forming the interface.
  10. if interface subdomain IDs are supplied in surface-builder mode.
  11. if manager mode identifies an interface using the same subdomain twice.
  12. if a signed distance is requested from a function that is neither a ParsedFunction nor a SignedDistanceToSurfaceMesh.
  13. if SignedDistanceToSurfaceMesh receives an in-out test user object that does not implement the point-in-surface check interface.

• shifted_boundary_method: Grain Boundary Case
• 18.3.1The system shall solve a shifted cohesive zone problem with volumetric locking correction on a polycrystalline grain structure whose grain IDs and interfaces are determined from one complete boundary mesh.
• 18.3.2The system shall orient true-interface normals consistently regardless of interface-subdomain pair ordering.
• 18.3.3The system shall retain an element input subdomain when no grain occupancy is selected.
• 18.3.4The system shall preserve grain names when boundary subdomain IDs are zero-based and noncontiguous.
• 18.3.5The system shall solve a shifted cohesive zone problem on a polycrystalline grain structure using a separately loaded surface mesh for each grain interface.
• 18.3.6The system shall associate each surrogate boundary with a user-selected saved surface mesh.
• 18.3.7The system shall throw an error
  1. if the maximum k-d tree leaf size is nonpositive.
  2. if a saved surface mesh is not provided for each shifted cohesive zone boundary.
  3. if one saved surface mesh is reused for multiple shifted cohesive zone boundaries.
  4. if one explicit subdomain pair is not provided for each surrogate boundary.
  5. if an explicit interface entry does not contain two subdomain IDs.
  6. if the two subdomain IDs in an explicit interface entry are not distinct.
  7. if explicit and automatically generated distance sources are both specified.
  8. if an explicit subdomain pair is absent from the detected complete interface.
  9. if partially overlapping interface faces are found in a nonconformal complete interface mesh.

• shifted_boundary_method: In Out Test
• 18.4.1The system shall be capable of performing point-in-polyhedron in-out testing to reclassify elements inside/outside a closed surface for different lambda cut fractions
  1. in 2D with lambda = 1.
  2. in 2D with lambda = 0.5.
  3. in 2D with lambda = 0.
  4. in 3D with lambda = 1.
  5. in 3D with lambda = 0.5.
  6. in 3D with lambda = 0.
• 18.4.2The system shall produce an in-out classification from an explicit axis-aligned ray that matches the classification from the automatically selected PCA ray direction, confirming the auto direction is reproducible for an anisotropic surface
  1. in 2D.
  2. in 3D.
• 18.4.3The system shall reject an InterceptedElementModifier lambda outside the inclusive range from zero to one.
• 18.4.4The system shall reject a non-positive tolerance for the point-in-polyhedron in-out test.
• 18.4.5The system shall reclassify elements inside/outside a surface described by a signed level-set function supplied to InterceptedElementModifier instead of a geometric in-out user object.
• 18.4.6The system shall allow an InterceptedElementModifier to classify points using any user object implementing the point-in-surface check interface, including a signed-function checker.
• 18.4.7The system shall assign a dedicated intercepted subdomain ID to elements the surface cuts through when mark_intercepted is enabled.
• 18.4.8The system shall reject an explicit lambda threshold when intercepted elements are assigned a dedicated subdomain ID.
• 18.4.9The system shall classify an element as intercepted when a closed surface lies within the element without enclosing any element nodes.
• 18.4.10The system shall classify an element as intercepted when a closed signed level-set surface lies within the element without enclosing any element nodes.
• 18.4.11The system shall classify an element whose nodes all lie outside a surface as intercepted rather than outside when the surface clips a finite region of the element interior, using the quadrature occupied-ratio check.
• 18.4.12The system shall apply the occupied-ratio in-out classification to a polygonal surface with sharp corners on a refined mesh, marking an element whose nodes all lie outside the polygon as intercepted where a corner clips the element interior.
• 18.4.13The system shall write the oriented bounding box and ray meshes used by the in-out test to file when the corresponding file names are provided.
• 18.4.14The system shall write the oriented bounding box and shortest-axis ray meshes built for the in-out test to standalone mesh files.
• 18.4.15The system shall report an error when mark_intercepted is enabled without specifying the intercepted subdomain ID.
• 18.4.16The system shall report an error when an InterceptedElementModifier is configured with neither an in-out test user object nor a signed distance function.
• 18.4.17The system shall report an error when an InterceptedElementModifier receives an in-out test user object that does not implement the point-in-surface check interface.
• 18.4.18The system shall report an error when an InterceptedElementModifier is configured with both an in-out test user object and a signed distance function.

• shifted_boundary_method: Shifted Cohesive Zone
• 18.5.1The system shall reproduce a manufactured displacement solution for a small-strain shifted cohesive zone problem across a non-interface-fitted material interface.
• 18.5.2The system shall solve a small-strain shifted cohesive zone problem on an angled, non-interface-fitted interface with an elastic traction-separation law.
• 18.5.3The system shall compute an automatic-differentiation Jacobian consistent with its residual for a small-strain shifted cohesive zone problem.
• 18.5.4The system shall compute an automatic-differentiation Jacobian consistent with its residual when the shifted cohesive zone directional correction is disabled.
• 18.5.5The system shall compute an automatic-differentiation Jacobian consistent with its residual when shifted cohesive zone evaluation is disabled.
• 18.5.6The system shall solve a small-strain shifted cohesive zone problem on an angled, non-interface-fitted interface using the Salehani-Irani traction law.
• 18.5.7The system shall solve a shifted cohesive zone problem on a non-interface-fitted triangular mesh using the Salehani-Irani traction law.
• 18.5.8The system shall reproduce the reaction-force history of an equivalent interface-fitted cohesive zone model within one percent by
  1. computing the reaction-force history for a shifted cohesive zone problem on a non-interface-fitted mesh,
  2. computing the reaction-force history for an equivalent interface-fitted cohesive zone problem,
  3. and comparing the two reaction-force histories.
• 18.5.9The system shall compute a Jacobian consistent with its residual for a small-strain shifted cohesive zone problem with directional correction enabled when automatic differentiation is disabled.
• 18.5.10The system shall compute a Jacobian consistent with its residual for a small-strain shifted cohesive zone problem with directional correction disabled when automatic differentiation is disabled.
• 18.5.11The system shall compute a Jacobian consistent with its residual for a cohesive zone problem with shifted evaluation disabled when automatic differentiation is disabled.
• 18.5.12The system shall compute a Jacobian consistent with its residual for a small-strain shifted cohesive zone problem when volumetric locking correction is inherited and automatic differentiation is disabled.
• 18.5.13The system shall compute a Jacobian consistent with its residual when matching volumetric locking correction settings are explicitly provided to the shifted cohesive zone and solid mechanics Physics blocks.
• 18.5.14The system shall solve a cohesive zone problem without distance data when shifted evaluation is disabled.
• 18.5.15The system shall use user-selected stress and constitutive-tangent properties with a common base-name prefix.
• 18.5.16The system shall use the derivative of first Piola-Kirchhoff stress with respect to deformation gradient as the default constitutive tangent.
• 18.5.17The system shall contract the derivative of first Piola-Kirchhoff stress with respect to deformation gradient into a Jacobian consistent with its residual.
• 18.5.18The system shall compute a Jacobian consistent with its residual when the first Piola-Kirchhoff tangent definition is specified explicitly.
• 18.5.19The system shall throw an error
  1. if a custom constitutive-tangent property has no explicit mathematical definition.
  2. if explicit tangent-property configuration is used with automatic differentiation enabled.
  3. if an explicit constitutive-tangent definition is used with automatic differentiation enabled.
• 18.5.20The system shall use a stress property with a user-selected base-name prefix when automatic differentiation is enabled.
• 18.5.21The system shall throw an error
  1. if explicitly specified volumetric locking correction settings differ between shifted cohesive zone and solid mechanics Physics blocks.
  2. if unsupported finite-strain cohesive zone kinematics are requested.
  3. if surface meshes are supplied when automatic distance generation is disabled.
  4. if the number of shifted cohesive zone displacement variables does not match the mesh dimension.
  5. if surface watertightness checks are enabled when automatic distance generation is disabled.
  6. if an interface matching tolerance is supplied without a complete interface mesh.
  7. if interface subdomain pairs are supplied without a complete interface mesh.
• 18.5.22The system shall report an error or warning
  1. if neither a surface function nor an interface manager is provided as the source of boundary distance data.
  2. if both surface-function and interface-manager sources of boundary distance data are provided.
  3. if interface subdomain pairs are provided when boundary distances come from surface functions instead of an interface manager.
  4. if a boundary is assigned more than once in a boundary distance user object.
  5. if one surface function is not provided for each configured surrogate boundary.
  6. if shifted cohesive zone evaluation requests distance data for a boundary on which distance data were not computed.
  7. if a computed boundary distance exceeds the estimated element scale.
• 18.5.23The system shall orient true-interface normals so their integrated area correction factor is positive across processes and threads.
• 18.5.24The system shall solve a shifted cohesive zone problem and output the results in Exodus format.

• shifted_boundary_method: Subdomain Element Modifier
• 18.6.1The system shall assign subdomain IDs to a background mesh from grain-boundary loops using per-subdomain in-out tests, marking each element with the grain that occupies the largest area fraction when several grains meet at interior corners.
• 18.6.2The system shall assign a dedicated intercepted subdomain ID to background elements straddling a grain boundary when mark_intercepted is enabled in SubdomainElementModifier.
• 18.6.3The system shall report, for an arbitrary point, which grain (subdomain) of a SurfaceMeshBySubdomainBuilder surface mesh contains it and whether it lies inside any grain, returning the invalid-subdomain sentinel and a not-inside result for points outside every grain.
• 18.6.4The system shall report whether the SurfaceMeshBySubdomainBuilder surface mesh is watertight when watertightness checking is enabled.
• 18.6.5The system shall throw an error
  1. if the SurfaceMeshBySubdomainBuilder surface mesh is distributed, since it requires a replicated mesh for its In-Out test.
  2. if the embedding mesh dimension does not match the surface mesh dimension plus one.
  3. if the SurfaceMeshBySubdomainBuilder surface mesh contains element types other than EDGE2 or TRI3.
  4. if the fixed_x_ray method is requested for PointInSubdomainCheckUO, which performs per-subdomain ray-casting and cannot use the whole-mesh TriangleManifold engine.
  5. if a point is contained in more than one subdomain of a PointInSubdomainCheckUO surface mesh, since a single-subdomain query is then ambiguous.

• shifted_boundary_method: Activeelementfractiontest.Unit Tests
• 18.7.1The system shall compute the fraction of a quadrilateral element occupied by the physical domain when the element is fully inside, fully outside, or cut in half by the true boundary.
• 18.7.2The system shall distinguish nodal and quadrature occupancy when a physical domain is enclosed within an element or its boundary passes through the element nodes.

• shifted_boundary_method: Classifypartialelementtest.Unit Tests
• 18.8.1The system shall classify fully active and fully inactive elements independently of partial-element options.
• 18.8.2The system shall assign the intercepted subdomain to partial elements when intercepted-element marking is enabled.
• 18.8.3The system shall classify partial elements by comparing their inactive fraction with the lambda threshold.
• 18.8.4The system shall apply partial-element classification when all nodes are active but the active fraction is not one.
• 18.8.5The system shall determine element inactivity from active fraction and the endpoint and interior values of the lambda threshold.
• 18.8.6The system shall prefer a fully occupied candidate subdomain over partial candidates and resolve multiple fully occupied candidates by lowest subdomain ID.
• 18.8.7The system shall select the largest partial subdomain occupancy, resolve fuzzy ties by lowest subdomain ID, and apply intercepted and lambda policies.
• 18.8.8The system shall select no subdomain when no candidate occupies any part of an element.

• shifted_boundary_method: Orientedboundingboxtest.Unit Tests
• 18.9.1The system shall write an oriented three-dimensional bounding box as a mesh containing a first-order hexahedral element whose vertices coincide with the corners of the box.
• 18.9.2The system shall write an oriented two-dimensional bounding box as a mesh containing a first-order quadrilateral element whose vertices coincide with the corners of the box.
• 18.9.3The system shall write a ray along the shortest axis of an oriented bounding box as a mesh containing a first-order line element.
• 18.9.4The system shall report geometry, projected coordinates, and point containment for an axis-aligned oriented bounding box.
• 18.9.5The system shall report projected coordinates and point containment in the local basis of a rotated oriented bounding box.
• 18.9.6The system shall initialize the corners and centroid of an oriented bounding box constructed without geometric data at the origin.

• shifted_boundary_method: Sbmdistancefunctiontest.Unit Tests
• 18.10.1The system shall compute the vector from a point to the zero level set of a signed-distance function.
• 18.10.2The system shall return a zero distance vector for a function with zero gradient.
• 18.10.3The system shall compute the unit gradient normal of a signed-distance function.
• 18.10.4The system shall select the distance and normal vectors of the nearest surface from multiple functions.
• 18.10.5The system shall compute the signed distance to a union as the minimum signed distance of its component functions.
• 18.10.6The system shall reject unsupported function types when computing signed distance to a union.

• shifted_boundary_method: Sbmsurfacedistancetest.Unit Tests
• 18.11.1The system shall compute the normal distance vector from a point to a first-order line element when the normal projection of the point lies within the element.
• 18.11.2The system shall compute the distance vector from a point to the nearest endpoint of a first-order line element when the normal projection of the point lies outside the element.
• 18.11.3The system shall compute the direction and magnitude of the distance vector from a point to a tilted first-order line element.
• 18.11.4The system shall compute the normal distance vector from a point to a first-order triangular surface element when the normal projection of the point lies within the element.
• 18.11.5The system shall compute distance vectors from points on and off a tilted first-order triangular surface element to their nearest points on the element.

• shifted_boundary_method: Watertighttest.Unit Tests
• 18.12.1The system shall identify open and closed two-dimensional boundary loops as non-watertight and watertight, respectively.
• 18.12.2The system shall identify open and closed three-dimensional boundary surfaces as non-watertight and watertight, respectively.

Usability Requirements

Performance Requirements

System Interfaces

System Operations

!template! item key=reliability
Include text (in MooseDocs format) regarding the "reliability" template item here.
!template-end!

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 Shifted Boundary Method module is software only with no associated physical media. See System Requirements for a description of the minimum required hardware necessary for running the Shifted Boundary Method module.

Environmental Conditions

Not Applicable

System Security

MOOSE-based applications such as the Shifted Boundary Method module 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

The core framework and all modules in their 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 MOOSE 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 Shifted Boundary Method module development team follows the NQA-1 standards.

Packaging, Handling, Shipping and Transportation

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