Stochastic Tools Requirements Traceability Matrix

This template follows INL template TEM-214, "IT System Requirements Traceability Matrix."

commentnote

This document serves as an addendum to Framework Requirements Traceability Matrix and captures information for RTM specific to the Stochastic Tools module.

Introduction

Minimum System Requirements

In general, the following is required for MOOSE-based development:

A POSIX compliant Unix-like operating system. This includes any modern Linux-based operating system (e.g., Ubuntu, Fedora, Rocky, etc.), or a Macintosh machine running either of the last two MacOS releases.

HardwareInformation
CPU Architecturex86_64, ARM (Apple Silicon)
Memory8 GB (16 GBs for debug compilation)
Disk Space30GB

LibrariesVersion / Information
GCC9.0.0 - 13.3.1
LLVM/Clang14.0.6 - 19
Intel (ICC/ICX)Not supported at this time
Python3.10 - 3.13
Python Packagespackaging pyaml jinja2

System Purpose

The purpose of the MOOSE Stochastic Tools module includes, but is not limited to:

  • Providing a MOOSE-like interface for performing stochastic analysis on MOOSE-based models.

  • Sampling model parameters, running applications, and gathering data of interest that is both efficient (memory and runtime) and scalable.

  • Performing uncertainty quantification and sensitivity analysis with distributed data.

  • Training meta-models to develop fast-evaluation surrogates of the high-fidelity multiphysics model.

  • Providing a pluggable interface for these surrogates.

As such, the purpose of this module is not to provide physical model capabilities, which is typically the responsibility of other MOOSE modules and dependent applications, but to provide data creation and processing capabilities in stochastic analysis.

System Scope

The MOOSE Stochastic Tools module builds on the existing framework MultiApps system and provides several additional systems to address its purpose. To address the efficient evaluation of multiphysics models, the MultiApps system is extended to include a "batch" mode of execution. This mode provides a memory efficient way of building MooseApp instances and reusing them for different perturbations of input parameters. This is useful for stochastic simulations with many, many samples to be run without holding them in memory or re-initializing potentially costly data allocation. The additional systems that the Stochastic Tools module provides include: Distributions, Samplers, Trainers, and Surrogates. Distributions are functions defining the uncertainty of input parameters and provides an interface for computing probability density, cumulative probability, and quantiles. Samplers define the sampling scheme of the stochastic analysis, whether it be random or deterministic. Trainers are objects that build meta-models meant to be used as surrogates or reduced-order models of the multiphysics model. The resulting reduced model is able to be saved in a meta-data file and reloaded for future use. Surrogates take the data created from a Trainer and provide functionality to evaluate the model. The module also provides capabilities for computing quantities related to basic uncertainty quantification and sensitivity analysis using the framework's Reporters system.

Assumptions and Dependencies

The Stochastic Tools module is developed using MOOSE and can itself be based on various MOOSE modules, as such the RTM for the Stochastic Tools module is dependent upon the files listed at the beginning of this document.

Pre-test Instructions/Environment/Setup

Ideally all testing should be performed on a clean test machine following one of the supported configurations setup by the test system engineer. Testing may be performed on local workstations and cluster systems containing supported operating systems.

The repository should be clean prior to building and testing. When using "git" this can be done by doing a force clean in the main repository and each one of the submodules:


git clean -xfd
git submodule foreach 'git clean -xfd'

All tests must pass in accordance with the type of test being performed. This list can be found in the Software Test Plan.

Changelog Issue Revisions

Errors in changelog references can sometimes occur as a result of typos or conversion errors. If any need to be noted by the development team, they will be noted here.

The changelog for all code residing in the MOOSE repository is located in the MOOSE RTM.

System Requirements Traceability

Functional Requirements

  • stochastic_tools: Controls
  • 20.3.1The system shall be able to read a neural network from a parameter file and use it to control a transient process.

    Specification(s): read-parameters

    Design: LibtorchDRLControl

    Issue(s): #19571

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • 20.3.2The system shall be able to hold a DRL control signal over a multi-step control period and advance the observation history once per period.

    Specification(s): read-parameters-period

    Design: LibtorchDRLControl

    Issue(s): #19571

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • 20.3.3The system shall be able to control a transient process with a bounded neural network read from a parameter file, sampling each action within the bounds.

    Specification(s): read-parameters-bounded

    Design: LibtorchDRLControl

    Issue(s): #19571

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • 20.3.4The system shall be able to exponentially smooth the control signal applied by a DRL controller.

    Specification(s): read-parameters-smoothed

    Design: LibtorchDRLControl

    Issue(s): #19571

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • 20.3.5The system shall be able to run with a DRL controller without having a neural net initialized in it.

    Specification(s): without-nn

    Design: LibtorchDRLControl

    Issue(s): #19571

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • 20.3.6The system shall reject DRL controller execute flags other than timestep begin.

    Specification(s): invalid-execute-on

    Design: LibtorchDRLControl

    Issue(s): #19571

    Collection(s): FUNCTIONALFAILURE_ANALYSIS

    Type(s): RunException

  • stochastic_tools: Ics
  • 20.6.1The system shall generate parallel agnostic random initial conditions using a distribution function.

    Specification(s): generate

    Design: RandomIC

    Issue(s): #5567#11901#9710

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

  • 20.6.2The system shall generate an error the random initial condition is used with both a distribution and min or max value defined.

    Specification(s): test_err_distribution_and_min_max

    Design: RandomIC

    Issue(s): #5567#11901#9710

    Collection(s): FUNCTIONALFAILURE_ANALYSIS

    Type(s): RunException

    Prerequisite(s): 20.6.1

  • stochastic_tools: Userobjects
  • 20.13.1The system shall be able to create a surrogate model for the solution coordinates in the latent space.

    Specification(s): create_surrogate

    Design: InverseMapping

    Issue(s): #23619

    Collection(s): FUNCTIONAL

    Type(s): CheckFiles

  • 20.13.2The system should be able to reconstruct a full solution field for a given variable based on
    1. coordinates determined by a surrogate model.
    2. manually specified coordinates.

    Specification(s): inverse_map/with_surrogate, inverse_map/with_manual_input

    Design: InverseMapping

    Issue(s): #23619

    Collection(s): FUNCTIONAL

    Type(s): Exodiff

    Prerequisite(s): 20.13.1

  • 20.13.3The system shall be bale to reconstruct linearly parameterized functions exactly with a few spatial modes using
    1. polynomial regression surrogates for the expansion coefficients.

    Specification(s): inverse_map_verification/with_polyreg_csv

    Design: InverseMapping

    Issue(s): #23619

    Collection(s): FUNCTIONAL

    Type(s): CSVDiff

    Prerequisite(s): 20.13.1

  • stochastic_tools: Variablemappings
  • 20.14.1The system should be able to build a variable mapping by computing the SVD of a snapshot matrix in serial.

    Specification(s): svd_1_proc_per_app

    Design: PODMapping

    Issue(s): #23619

    Collection(s): FUNCTIONAL

    Type(s): JSONDiff

  • 20.14.2The system should be able to build a variable mapping by computing the SVD of a snapshot matrix in parallel.

    Specification(s): svd_2_proc_per_app

    Design: PODMapping

    Issue(s): #23619

    Collection(s): FUNCTIONAL

    Type(s): JSONDiff

  • 20.14.3The system should be able to build a variable mapping by computing the SVD of a snapshot matrix in parallel with having data on only root processors.

    Specification(s): svd_2_proc_per_app_root

    Design: PODMapping

    Issue(s): #23619

    Collection(s): FUNCTIONAL

    Type(s): JSONDiff

  • stochastic_tools: Teststandardizer.Unit Tests
  • 20.19.1The system shall compute and provide access to the per-column mean and standard deviation of a data set via computeSet, getMean, and getStdDev.

    Specification(s): get_mean

    Design: Standardizer

    Issue(s): #30564

    Collection(s): FUNCTIONAL

    Type(s): GoogleTest

  • 20.19.2The system shall center and scale a tensor using the mean and standard deviation computed by a Standardizer via getStandardized.

    Specification(s): get_standardized

    Design: Standardizer

    Issue(s): #30564

    Collection(s): FUNCTIONAL

    Type(s): GoogleTest

  • 20.19.3The system shall recover the original tensor values when reversing a Standardizer getStandardized transform via getDestandardized.

    Specification(s): get_destandardized

    Design: Standardizer

    Issue(s): #30564

    Collection(s): FUNCTIONAL

    Type(s): GoogleTest

  • 20.19.4The system shall scale a tensor by a Standardizer computed standard deviation via getDescaled, without applying any mean shift.

    Specification(s): get_descaled

    Design: Standardizer

    Issue(s): #30564

    Collection(s): FUNCTIONAL

    Type(s): GoogleTest

  • 20.19.5The system shall scale a tensor by dividing it by a Standardizer computed standard deviation via getScaled, without applying any mean shift.

    Specification(s): get_scaled

    Design: Standardizer

    Issue(s): #30564

    Collection(s): FUNCTIONAL

    Type(s): GoogleTest

  • 20.19.6The system shall store and load a 2-dimensional torch::Tensor as recoverable data, preserving its shape and values.

    Specification(s): tensor_data_store_load

    Design: DataIO

    Issue(s): #30564

    Collection(s): FUNCTIONAL

    Type(s): GoogleTest

  • 20.19.7The system shall store and load a scalar (0-dimensional) torch::Tensor as recoverable data, preserving its rank and value.

    Specification(s): tensor_scalar_data_store_load

    Design: DataIO

    Issue(s): #30564

    Collection(s): FUNCTIONAL

    Type(s): GoogleTest

  • 20.19.8The system shall store and load a 1-dimensional torch::Tensor as recoverable data, preserving its shape and values.

    Specification(s): tensor_vector_data_store_load

    Design: DataIO

    Issue(s): #30564

    Collection(s): FUNCTIONAL

    Type(s): GoogleTest

  • 20.19.9The system shall store and load a non-contiguous torch::Tensor as recoverable data, preserving its shape and values.

    Specification(s): tensor_data_store_load_non_contiguous

    Design: DataIO

    Issue(s): #30564

    Collection(s): FUNCTIONAL

    Type(s): GoogleTest

  • 20.19.10The system shall store and load a Standardizer with a computed mean and standard deviation as recoverable data, preserving both moments.

    Specification(s): standardizer_data_store_load

    Design: Standardizer

    Issue(s): #30564

    Collection(s): FUNCTIONAL

    Type(s): GoogleTest

  • 20.19.11The system shall support storing and loading recoverable data for a Standardizer that has not yet computed a mean/standard deviation set.

    Specification(s): empty_data_store_load

    Design: Standardizer

    Issue(s): #32193

    Collection(s): FUNCTIONAL

    Type(s): GoogleTest

Usability Requirements

No requirements of this type exist for this application, beyond those of its dependencies.

Performance Requirements

No requirements of this type exist for this application, beyond those of its dependencies.

System Interface Requirements

No requirements of this type exist for this application, beyond those of its dependencies.

References

No citations exist within this document.