Optimization System Requirements Specification

This template follows INL template TEM-135, "IT System Requirements Specification".

note

This document serves as an addendum to Framework System Requirements Specification and captures information for SRS specific to the Optimization module.

Framework System Requirements Specification

Introduction

System Purpose

The purpose of the MOOSE Optimization module is to control model parameters such that they minimize a defined objective. An example would be to search for material property values so that the solution matches experimental results. 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.

System Scope

The MOOSE Optimization module utilizes several MOOSE systems to perform optimization on physics models. The design relies on a customized Executioner to drive the optimization algorithm. This Executioner calls a specific type of Reporter known as a OptimizationReporter, which defines the parameter space, objective, gradient, and Hessian functions necessary for the optimization methods. Along with calling this Reporter, the Executioner calls MultiApps and Transfers that are responsible for passing parameters to the physics model, running the model, and gathering the necessary data to compute the objective, gradient, and Hessian. Typically, one sub-application defines the underlying physics for the objective computation, another defines an adjoint version of the model for the gradient computation, and another defines a homogeneous version of the model for the matrix-free Hessian computation. All data from these applications is gathered in the OptimizationReporter, which is then sent to the optimization Executioner. The resulting output is the value of the optimized parameters and the solution of physics model with these parameters. The scope of the Optimization module includes, but is not limited to:

Inverse optimization
Shape optimization
Topology optimization

System Overview

System Context

The Optimization 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 Optimization 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 Optimization module and other MOOSE-based applications.

System Functions

Since the Optimization 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 Optimization 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 Optimization module:

Optimization module Developers: These are the core developers of the Optimization 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 Optimization 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 Optimization 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 Optimization module is developed using MOOSE and can itself be based on various MOOSE modules, as such the SRS for the Optimization 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.

The Optimization module is designed with the fewest possible constraints on hardware and software. For more context on this point, the Optimization module SRS defers to the framework Assumptions and Dependencies. Any physics-based or mathematics-based assumptions in code simulations and code objects are highlighted in their respective documentation pages.

References

ISO/IEC/IEEE 24765:2010(E). Systems and software engineering—Vocabulary. first edition, December 15 2010.

@manual{ISO-systems-software,
    author = "24765:2010(E), ISO/IEC/IEEE",
    title = "Systems and software engineering---Vocabulary",
    edition = "First",
    year = "2010",
    month = "December 15"
}

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.

@manual{ASME-NQA-1-2008,
    author = "NQA-1, ASME",
    title = "ASME NQA-1-2008 with the NQA-1a-2009 addenda: Quality Assurance Requirements for Nuclear Facility Applications",
    orginization = "American Socieity of Mechanical Engineers",
    year = "2009",
    month = "August 31",
    edition = "First"
}

Definitions and Acronyms

This section defines, or provides the definition of, all terms and acronyms required to properly understand this specification.

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

Acronym	Description
INL	Idaho National Laboratory
LGPL	GNU Lesser General Public License
MOOSE	Multiphysics Object Oriented Simulation Environment
NQA-1	Nuclear Quality Assurance Level 1
POSIX	Portable Operating System Interface
SRS	Software Requirement Specification

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.

Hardware	Information
CPU Architecture	x86_64, ARM (Apple Silicon)
Memory	8 GB (16 GBs for debug compilation)
Disk Space	30GB

Libraries	Version / Information
GCC	8.5.0 - 12.2.1
LLVM/Clang	10.0.1 - 16.0.6
Intel (ICC/ICX)	Not supported at this time
Python	3.7 - 3.11
Python Packages	packaging pyaml jinja2

Functional Requirements

optimization: Dirackernels
11.1.1
The system shall support point sources with locations, times, and values given by a vector values with
1. forward time stepping;
2. reverse time stepping;

optimization: Executioners
11.2.1
The system shall be able to debug a optimization solve by
1. using finite-difference to compute the gradient;
2. testing hand-coded gradient;
11.2.2The system shall minimize a constrained quadratic objective function from a test object using the TAO ALMM solver.
11.2.3The system shall minimize an inequality constrained quadratic objective function from a test object.
11.2.4The system shall be able to minimize a constrained shape optimization problem using the ALMM algorithm.
11.2.5
The system shall by able to solve the adjoint version of steady-state problems that
1. are self-adjoint,
2. have non-homogeneous boundary conditions,
3. have multiple coupled variables,
4. use array variables, and
5. have non-linear material properties.
11.2.6
The system shall be able to solve the adjoint version of transient problems that
1. are self-adjoint,
2. have multiple coupled variables,
3. have non-linear steady-state material properties, and
4. have non-uniform time stepping.

optimization: Functions
11.3.1
The system shall be able to compute an auxiliary variable based on data from reporter values with
1. x-coordinate data;
2. x- and y-coordinate data;
3. x-, y-, and z-coordinate data;
4. time, x-, y-, and z-coordinate data;
11.3.2
The system shall report an error if
1. the size of value vector is wrong;
2. x-coordinate data is wrong size;
3. y-coordinate data is wrong size;
4. z-coordinate data is wrong size;
5. time data is wrong size;
11.3.3
The system shall be able to evaluate a mesh-based interpolation function by
1. creating first-order mesh and
2. evaluating the first-order parameter values;
3. creating second-order mesh and
4. evaluating the second-order parameter values;
5. creating piece-wise constant mesh and
6. evaluating the piece-wise constant parameter values;
7. evaluating transient parameter values;
11.3.4
The system shall support parsed function expressions with parameter values by
1. computing parameter gradient;
2. erroring if vector is incorrect size;

optimization: Misc
11.4.1The system shall throw out a warning when scalings are assigned to adjoint variable to remind users that no scaling will be performed for adjoint system.

optimization: Optimizationreporter
11.5.1
The system shall be able to scale linear and constant functions involved in two separate Neumann boundary conditions both applied to the same sideset using two parsed functions and the scale of the linear and constant functions are both being parameterized using
1. a matrix-free Hessian approach or
2. automatic adjoint evaluation.
11.5.2
The system shall be able to invert for the value of a material property in two separate regions using
1. a gradient evaluated in a separate multiapp with parameter initial conditons 1.5x higher than the true solution;
2. a gradient evaluated in a separate multiapp using Tikhonov regularization and parameter initial conditons 3x higher than the true solution; or
3. a gradient evaluated with an automatically computed adjoint.
11.5.3
The system shall be able to optimize the magnitude of a source for a
1. linear diffusion problem;
2. diffusion problem with nonlinear coefficient;
11.5.4The system shall be able to minimize an objective function that is reporter transfer using TAO and output parameters used for each evaulation.
11.5.5
The system shall be able to invert for point loads using the general optimization reporter with
1. the measurement data defined on the forward_and_adjoint app;
2. the measurement data defined on the main app and transferred to theforward_and_adjoint app while maintaining the correct preconditioning on the adjoint system;
3. the measurment data defined on the separate subapps;
4. the measurment data defined on the separate subapps and using regularization;
11.5.6The system shall be able to perform gradient based material parameter inversion for a single material property.
11.5.7
The system shall be able to perform inverse optimization on a source that is represented by a mesh by
1. creating the source mesh;
2. performing the inverse optimization with a piece-wise source;
3. performing the inverse optimization with a linearly varying source;
4. performing the inverse optimization with a quadratically varying source;
5. performing the inverse optimization with bounds;
6. performing the inverse optimization with an automatically computed adjoint;
7. creating a mesh with initial conditions;
8. performing the inverse optimization with exact solution initial conditions that will make it converge in a single step;
11.5.8
The system shall throw an error when performing inverse optimization on mesh-based parameters if there is a mismatch between the number of parameters and the number of
1. meshes;
2. finite-element families;
3. finite-element orders;
4. initial conditions;
11.5.9
The system shall throw an error when performing inverse optimization on mesh-based parameters if the parameter function spaces do not match the space defined in the
1. forward problem;
2. adjoint problem;
11.5.10The system shall be able perform inverse source optimization on a problem with nonlinear material properties using automatically computed adjoint.
11.5.11
The system shall correctly read in parameter data defined in the input file
1. measurement data from the input file;
2. with lower bounds, upper bounds and initial conditions provided for every parameter and measurement data from a CSV file;
3. with lower bounds, upper bounds and initial conditions constant for each group and measurement data from a CSV file;
4. with lower bounds, upper bounds and initial conditions are a mix of constant per group and every parameter in a group and measurement data from a CSV file;
5. and error if parameters are provided but do not include a parameter for every group;
6. and error if an incorrect number of parameters are provided for a group;
11.5.12The system shall be able to read variable weights and use them to scale the misfit.
11.5.13
The system shall correctly read in one parameter group defined on the mesh
1. by first creating the parameter mesh containing the data;
2. with initial conditions, upper and lower bounds defined on the mesh for all timesteps;
3. with initial conditions, upper and lower bounds defined in input file;
4. with initial conditions and lower bound read from input file and upper bound read from the last timestep in the mesh.
11.5.14
The system shall correctly read in two groups of parameter data defined on the mesh
1. for initial conditions, upper and lower bounds defined on the mesh for all timesteps;
2. for initial conditions, upper and lower bounds defined in input file;
3. for initial conditions and lower bound read from input file and upper bound read from the last timestep in the mesh;
4. for the first group being first order Lagrange and second group being second order Lagrange nodal variables.
11.5.15
The system shall throw an error when parameter data is incorrectly defined
1. by having input and mesh parameters for the same bound;
2. by having a parameter not on the exodus mesh;
3. by using nodal and elemental exodus variables to define parameter data in the same parameter group;
4. by not having the same number of optimization timesteps and timesteps for reading parameter data from the mesh;
5. by specifying a timestep for reading parameter data from the exodus file but not parameter data is being read from the mesh because it is all specified in the input file;
6. by specifying a timestep that is bigger than the timestpes on the exodus the exodus mesh.
11.5.16
The system shall be able to invert for point loads using
1. Hessian-based optimization,
2. ill-posed Hessian-based optimization with Tikhonov regularization,
3. gradient-based optimization,
4. ill-posed gradient-based optimization with Tikhonov regularization,
5. gradient-based optimization with an automatically computed adjoint that uses the same preconditioner as the forward solve, or
6. gradient-based optimization with an automatically computed adjoint, with Tikhonov regularization, and initial conditions do not affect the converged regularized solution, or
7. print finite difference gradient information to the screen when using the automatically formed adjoint.

optimization: Outputs
11.6.1The system shall be able to perform gradient based material parameter inversion for a single material property and output the iteration-wise exodus output for the adjoint problem.
11.6.2The system shall be able to invert for point loads using gradient-based optimization with an automatically computed adjoint and output the exodus output per iteration for the combined forward and adjoint problem variables.

optimization: Reporter
11.7.1The system shall create synthetic transient data in a consumable format.

optimization: Reporters
11.8.1The system shall be able to find an optimal value to a linear combination of parallel forward problems run using the sampler system.
11.8.2The system shall be able to row sum a vector of vectors into a single vector, perform a dot product between two vectors and sum all of the entries of a single vector.
11.8.3The system shall throw a reasonable error when reducing a vectors of vectors into a single vector and the input vectors contained in the vector of vectors do not have the same size.
11.8.4The system shall throw a reasonable error when the vectors being combined into a single vector using arithmetic operations are not the same size.

optimization: Simp
11.9.1The system shall be able to run a diffusion problem through the density update machinery with filtered fake sensitivities to optimize the material distribution applying a bisection algorithm.
11.9.2The system shall be able to run a diffusion problem through the density update machinery with filtered fake sensitivities to optimize the material distribution applying a bisection algorithm to a block restricted system.
11.9.3The system shall be able to run a diffusion problem through the density update for multiple materials, volume constraint, and cost constraint machinery with filtered fake sensitivities to optimize the material distribution applying a bisection algorithm.
11.9.4The system shall be able to run a diffusion problem through the density update for multiple materials, volume constraint, and cost constraint machinery with filtered fake sensitivities to optimize the material distribution applying a bisection algorithm to a block restricted system.

optimization: Userobjects
11.10.1
The system shall be able to load a time-dependent solution from an exodus file while reversing the timesteps by
1. producing the exodus file;
2. loading on to the same mesh;
3. loading on to a coarser mesh;
4. interpolating different time steps;
5. erroring if file is not exodus;

optimization: Vectorpostprocessors
11.11.1The system shall be able to compute the inner product of adjoint strain and derivative of stress with respect to the material property value.
11.11.2The system shall be able to compute the inner product of two RankTwoTensor material properties and match the result from the batch material implementation.
11.11.3The system shall be able to compute the inner product between two variables weighted by the derivative of a function with respect to the vector it depends on.
11.11.4The system shall be able to compute the inner product of a variable and a nearest node optimization volumetric source function.

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 Interfaces

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

System Operations

Human System Integration Requirements

The Optimization module is command line driven and conforms to all standard terminal behaviors. Specific human system interaction accommodations shall be a function of the end-user's terminal. MOOSE (and therefore the Optimization module) does support optional coloring within the terminal's ability to display color, which may be disabled.

Maintainability

The latest working version (defined as the version that passes all tests in the current regression test suite) shall be publicly available at all times through the repository host provider.
Flaws identified in the system shall be reported and tracked in a ticket or issue based system. The technical lead will determine the severity and priority of all reported issues and assign resources at their discretion to resolve identified issues.
The software maintainers will entertain all proposed changes to the system in a timely manner (within two business days).
The core software in its entirety will be made available under the terms of a designated software license. These license terms are outlined in the LICENSE file alongside the Optimization module source code. As a MOOSE physics module, the license for the Optimization module is identical to that of the framework - that is, the LGPL version 2.1 license.

Reliability

The regression test suite will cover at least 86% of all lines of code within the Optimization module at all times. Known regressions will be recorded and tracked (see Maintainability) to an independent and satisfactory resolution.

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:

Command Line Flag	Description of mode
`-i <input_file>`	Normal execution mode
`--split-mesh <splits>`	Read the mesh block splitting the mesh into two or more pieces for use in a subsequent run
`--use-split`	(implies -i flag) Execute the simulation but use pre-split mesh files instead of the mesh from the input file
`--yaml`	Output all object descriptions and available parameters in YAML format
`--json`	Output all object descriptions and available parameters in JSON format
`--syntax`	Output all registered syntax
`--registry`	Output all known objects and actions
`--registry-hit`	Output all known objects and actions in HIT format
`--mesh-only` (implies -i flag)	Run only the mesh related tasks and output the final mesh that would be used for the simulation
`--start-in-debugger <debugger>`	Start the simulation attached to the supplied debugger

note

The list of system-modes may not be extensive as the system is designed to be extendable to end-user applications. The complete list of command line options for applications can be obtained by running the executable with zero arguments. See the command line usage.

Physical Characteristics

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

Environmental Conditions

Not Applicable

System Security

MOOSE-based applications such as the Optimization 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 Optimization 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 Optimization module source code. However, some MOOSE-based applications that use the Optimization module may be export-controlled, in which case all export control restrictions must be adhered to when packaging and shipping media.

Verification

The regression test suite will employ several verification tests using comparison against known analytical solutions, the method of manufactured solutions, and convergence rate analysis.

Introduction
System Overview
References
Definitions and Acronyms
System Requirements
Verification