Software Overview

This repository uses the WAVES computational workflow tool (which utilizes the SCons automated build system) to configure and execute upscaling workflows. Workflows contained in this repository use a wide array of software. As such, basic description is provided for how to properly install and link required software.

Currently, the following DNS codes are considered:

Abaqus implicit finite element (FE) and
Ratel implicit FE.

Abaqus explicit FE and GEOS explicit material point method (MPM) DNS will be added in the future.

Additionally, Cubit is used for a number of meshing operations. For users without access to Cubit, several example meshes are contained in model_package/meshes/, however, functionality of workflows will be limited.

Tardigrade software products include:

Micromorphic Filter
Tardigrade-MOOSE
Micromorphic Calibration Tool
Micromorphic Linear Elastic Constraints

The Tardigrade software must be properly configured to perform any upscaling analyses. The DNS software, on the other hand, is not necessarily required.

Conda Environment

AEA server environments

A shared AEA Compute environment is maintained on AEA servers. See the AEA Compute environment documentation for the official use and activation instructions. A minimal activation description is included below for convenience.

Add the AEA modulefiles directory

$ module use /projects/aea_compute/modulefiles

Load the shared environment modulefile
```
$ module load tardigrade-examples-env
```

Local environments

For users external to LANL systems, an environment to run workflows in this repository can be installed in a Conda environment with the Conda package manager. Users are recommended to follow the conda installation instructions provided by MOOSE_conda and to keep MOOSE packages up to date whenever rebuilding software required by this project (MOOSE_up_to_date). See the Conda installation and Conda environment management documentation for more details about using Conda.

Create the base environment with Mamba and Python 3.10 if it doesn’t exist

$ conda create --name tardigrade-examples-env mamba python=3.10 moose-dev --channel https://conda.software.inl.gov/public --channel conda-forge

Activate the environment

$ conda activate tardigrade-examples-env

Install packages

$ mamba install --file environment.txt --channel https://conda.software.inl.gov/public --channel conda-forge

Warning

Whenever rebuilding MOOSE related software, it is recommended to completely remove and rebuild the conda environment!!! More information is provided here: MOOSE_up_to_date.

SCons Build System

The SCons automated build system is used to execute workflows. This section will discuss some common build operations. An abbreviated options description can be displayed with scons -H. For a full list of SCons command line options and target build behavior, see the SCons manpage. The SCons manpage is also installed with SCons in the environment and can be opened from the command line as man scons in the AEA Compute environment. In local environments, the manpage may not be in the man program’s search path, MANPATH. You can find the manpage file and make them available with something similar to any of the following, in increasing order of required background knowledge.

# Activate the environment
conda activate tardigrade-examples-env

# Find the scons manpage file
$ find $CONDA_PREFIX -name scons.1
/path/to/tardigrade-examples-env/scons.1

# Open manpage directly
$ man $CONDA_PREFIX/scons.1

# Link SCons manpage to expected path and update MANPATH
$ ln -s $CONDA_PREFIX/scons.1 $CONDA_PREFIX/man/man1/scons.1
$ export MANPATH=$MANPATH:$CONDA_PREFIX/man
$ man scons

View project specific command line options
```
$ scons -h
...
```

This project limits the default target list to the documentation with the SCons Default command. Simulation targets must be specified directly on the command line. The SCons “all targets” character, ., may also be specified to build every target in the repository, including all simulation targets. Simulation targets may be specified by output file name or by target alias, which is set to match the parent directory for the target configuration, e.g. Abaqus_elastic_cylinder.

View the default targets and target aliases
```
$ scons -h
...
```
Build default targets
```
$ scons
```
Build all targets
```
$ scons .
```
Build a specific target
```
$ scons <target name>
```
Remove all build target artifacts
```
$ scons . --clean
```

PetaLibrary Data Copy

Several WAVES workflows upscale DNS run by others from the CU Boulder PSAAP project and stored in the PetaLibrary. These DNS results may be copied using the following command:

$ scons --peta-data-copy

A user will be asked for their identikey, password, and a dual authentication requrest before the secure copy (SCP) transfers files.

Note

This data may only be accessed for users with a Colorado ResearchComputing account with an allocation to the appropriate PSAAP user group.

Configure paths to required software

Paths to required software are specified by modifying the contents of the config_software.yml file in the root directory. By default, these paths are empty so they must be configured. Upon executing the scons -h command, one may see a number of local options including --config-software. Additionally, a user may modify the contents of config.yml directly.

Configure the paths to required software
```
$ scons --config-software
```

The user will be asked if new or additional paths will be appended to the config_software.yml file. Some of these paths are paths to executable programs (e.g. Abaqus, Ratel, and Tardigrade-MOOSE), while some are paths to Python programs and scripts.

The config_software.yml file is read into the SCons configuration file (SConstruct). The YAML file is parsed into a dictionary where each key corresponds to a program and each entry is a list of program paths. For exeuctable programs, the waves.scons_extensions.find_program() function is used to search the list of paths with the first executable found being set as the program path. For paths to importable Python objects, only the last path in the list is set.

Further details for installing and configuring required software is discussed in the following section Software Installation.