User Manual

Activate 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.

The Conda packages found in environment.yml are reproduced in the Dependencies section.

Build

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
```

Test

Unlike software projects, the primary model/simulation project tests are the successful completion of some subset of the simulation targets. If the selected simulations run successfully, then the target passes. Secondary project tests will use SCons to execute unit and integration testing for project specific scripts, such as journal files and Python processing scripts.

Build the required target(s). Test targets may not be part of the default target list. If so, each target will need to be listed explicitly or the “all targets” character, ., should be used to build all project targets.
```
$ scons <target_1_name> <target-2_name>
```
Run all simulation and test targets. Try to run all targets even if some fail.
```
scons . --keep-going
```

Test Local Module

When testing CLI changes locally, the waves module must be run as a script. We must also set the PYTHONPATH in order to include the current waves module when operating on a configuration that imports waves.

Below is an example of a visualization test of an SConstruct file using the local waves module.

$ pwd
path/to/local/git/clone/waves/
$ PYTHONPATH=$PWD python -m waves.main visualize . --sconstruct /path/to/local/SConstruct

Documentation

The documentation build is also automated with SCons as the documentation target alias.

Build all documentation targets
```
$ scons documentation
```
Build the HTML documentation
```
$ scons html
```