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

Local environments#

SCons and WAVES can be installed in a Conda environment with the Conda package manager. See the Conda installation and Conda environment management documentation for more details about using Conda.

Create the environment if it doesn’t exist

$ conda env create --name modsim-template-env --file environment.yml

Activate the environment
```
$ conda activate modsim-template-env
```

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

Build#

This project uses the SCons build system. 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 modsim-template-env

# Find the scons manpage file
$ find $CONDA_PREFIX -name scons.1
/path/to/modsim-template-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. tutorial_01_geometry.

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
```
For debugging workflows, use the verbose output option of SCons
```
$ scons target --debug=explain
```

Because SCons uses Python as a scripting language, the usual Python debugging techniques may be placed directly in the configuration file, as well: https://docs.python.org/3/library/pdb.html.

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.

In this project, the regression test suite includes simulation datachecks, documentation builds, and unit testing. For convenience, the regression suite workflows are collected under the regression alias.

Run the regression tests
```
$ scons regression
```
Run all simulation and test targets. Try to run all targets even if some fail.
```
scons regression --keep-going
```

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

User Manual

Contents